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PREFACE 



This manual describes how to write user extensions to the 
Multics Emacs editor. The reader should be thoroughly familiar 
with the Emacs editor, proficient in its use, and acquainted with 
its visible organization. The Emacs Text Editor User ' s Guide , 
Order No. CH27, provides this necessary information. The 
methods for writing terminal control modules (CTLs) to support 
additional terminal types are also described here. 

Programming knowledge is not necessary to write extensions 
successful!" althouch it is helpful. Section 1 is a short 
introduction to extension writing. Section 2 provides a short 
course in Lisp, the programming language used for writing 
extensions, and the language in which the Emacs editor itself is 
written. Basically, the extension writer only needs to learn 
enough about Lisp to be able to imitate examples. 

Section 3 shows, by example, how to write extensions. It 
includes the functions and forms most likely to be needed by the 
extension writer. Section 4 describes LDEBUG mode, the Emacs 
mode for debugging the Lisp code used in extensions. Finally, 
Section 5 demonstrates how to write a CTL to support a new 
terminal type. Again, the CTL writer uses existing CTLs to learn 
to write his own. 



The information and specifications in this document are subject to change without notice. This doc- 
ument contains information about Honeywell products or services that may not be available out- 
side the United States. Consult your Honeywell Marketing Representative. 

©Honeywell Information Systems Inc., 1983 File No.: 1L33, 1U33 

CJ52-01 



This manual contains sufficient information to effectively 
write and debug Multics Emacs extensions. However, it is not 
mtendedto be a reference document for either Lisp, in general - 
or Multics MacLisp. Reference documentation for MacLisD is 
available from: y 



MIT Information Processing Center 
Publications Office 
60 Vassar Street 
Cambridge, MA 02139 

Significant Changes in CJ52 - Q1A 
New Emacs functions include: 

kill-pop 
kill-ring-top 
reverse-regexp-search 
rotate-kill-ring 

New defcom keywords include: 

Gccleanup 
tepilogue 
&inverse 
Stnumeric- function 

For purposes of clarity and ease of use, the MPM set has 

^% n ,l e0 l?.t n ^ Zed ', Th *J ix former- MPM manuals, the Tools manual, 

and the RCP Users' Guide have been consolidated into a new set of 
three manuals: 

Multics Programmer's Reference Manual (AG91) 

contains all the reference material from the former 
eight manuals. 

Multics Commands and Active Functions (AG92) 

contains all the commands and active functions from the 
former eight manuals. 

Multics Subroutines and Input/Output Modules (AG93) 

contains all the subroutines and I/O modules from the 
former eight manuals. 
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The following manuals are obsolete: 

Name Order No, 

MPM Peripheral Input /Out put AX49 

MPM Subsystem Writers' Guide AK92 

Programming Tools AZ03 

MPM Communications I/O CC92 

Resource Control Users' Guide CT38 
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SECTION 1 
INTRODUCTION 



2* j An edltor extension is a user-provided capability, which is 
added to the editor to extend its power. It is different from a 
macro, which is simply a collection of editor requests gathered 
up ^ and (perhaps) given a name. Extensions are programs ; they are 
written in the language of the Multics Emacs environment. An 
extension is a body of code that augments the editor's 
capability, but does not embed or require knowledge of how data 
in the editor is stored or manipulated. In this sense, all of 
the_ word, sentence, paragraph, and Lisp-list requests, and the 
various "modes" (e.g., PL/I mode) are extensions. 

The person who wishes to add to his Emacs environment any 
powerful or sophisticated capability must learn to write 
extensions. The keyboard macro facility ( A X(, A X) ) is not 
intended for such usage. This manual explains how to write 
extensions. 

One of the guiding design principles in the Emacs editor was 
that the creation of editor extensions, either by the editor 
implementors or end users, should be in a programming language of 
established elegance and power. Lisp was the language chosen. 
This primer gives you a starting point for writing Lisp code to 
run as editor extensions in the Emacs environment. If you have 
some knowledge of Lisp already, it will be of value. However, it 
is assumed in this manual that the reader has no familiarity with 
Lisp, but does, perhaps, with PL/I or BASIC. 

For examples of extension coding, the extension writer's 
ultimate reference material will be the Emacs source. The Emacs 
mail system (RMAIL) , FORTRAN and PL/I modes, and the code for the 
word, sentence, and paragraph requests (along with most of the 
other code m the Emacs module e_macops_.lisp) are standard 
examples of extension code. Techniques, styles, and subtleties 
difficult to convey in print may be gleaned by careful study of 
this code. 
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SECTION 2 
AN INTRODUCTION TO LISP 



Lisp programs are built of functions , which are similar to 
procedures or subroutines in other languages, although more akin 
to PL/I and ALGOL functions. You write a Lisp program by 
creating a file full of function definitions . A function 
definition specifies the name of a function, and what it does. 
Here is a sample function definition: 

{defun addandmult (a b c) ;This is a comment 

(*■ (" a b) 
(+ a b c})) 

This defines a function named addandmult that takes three 
arguments, called a, b, and c. The addandmult function computes 
the result of multiplying the difference of a and b by the sum of 
a, b ? and c. and returns that number as a result , or value. The 
semicolon on the first line above begins a comment ; comments 
throughout the examples provide some additional information about 
the code. 



Here is another function definition: 

(defun squareprint (arg) 

(print "The square of") 
(print arg) 
(print "is") 
(print (* arg arg) ) 
5) 

This function prints the message "The square of", prints the 
value of its argument, prints the word "is", and prints the value 
of the square of its argument. In addition, it returns the value 
5. The function "squareprint" has side effects: it causes 
output on the terminal. It also returns a value, the number 5. 
Note that all Lisp functions produce a value; only some produce 
side effects. The first function defined returns the product of 
those numbers as a value; the second returns 5. 
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If you look at squareprint, you see that it consists of 
several statements , the "print statements" that print things. 
These statements are called forms , and they are, in fact, calls 
to other functions, in this case the builtin print function. In 
the form: 

(print "The square of") 

the string "The square- of" is being passed as an argument to the 
print function. Like 1 all functions, print returns a value, which 
is not used in this case* The side effect of printing something 
does occur. In the formt 

(+■■ a. b c) 

you are invoking the ">"' function, which is also builtin. _ The 
values of the parameter variables a, b, and c are passed to it as 
arguments. It returns a value, which is the requested sum, and 
produces no side effects* 



There are 
squareprint ; 



five forms in the function-definition for 



(print 
(print 
(print 
(print 
5 



square of") 



"The 

arg) 

"is") 

(* arg arg)) 



Forms immediately inside a function definition are executed 



sequentially, like statements in 
The value produced by the last 
itself returns. What does it mean 
not exactly the right term; what 
forms are evaluated. This means 



other programming languages. 

form is the one the function 
to "execute" a 5? Execute is 
really happens is that these 

that a value is produced from 



them. Evaluating a 5 produces the number 5; evaluating the forms 
(+ a b c) 

calls the "+" function with the appropriate arguments, and 
produces whatever value the "+" function returns. The value 
produced by the "print" function is something that is not 
interesting, but a value is produced. 
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Numbers, like 5, and strings, like "The square of", are said 
to evaluate to themselves. Things between parentheses, like: 

(+ a b c) 

(print "The square of") 

are calls to functions, which are evaluated by calling the 
function indicated, and producing the value it returns. 

Function calls have the syntax: 

(FUNCTIONNAME ARGF0RM1 ARGFORM2 ARGFORM3 ... ARGFORMn) 

where FUNCTIONNAME is the name of the function to call and the 
ARGFORMs are themselves forms, which are evaluated to produce the 
arguments to give to the function. Thus, to evaluate {i.e., 
"execute" and find the value returned) a form like: 

(+ (* a b) 
15 
c) 

a evaluate the inner form (* a b) to produce a value 

a evaluate the 15 to produce 15 (remember, numbers and 
strings evaluate to themselves) 

a evaluate the variable c to produce its value 

a pass these three values on to the "+" function, and 
return what it returns. 

The newlines are ignored. 

Thus, forms are either numbers like 5, strings like "is", 
variables like b, or function calls like (* a b). 

Variables are much like variables in other languages. A 
variable has a value, which is called its binding . At this 
stage, assume that this value must be a string or a number. When 
a function is invoked, the parameter variables (like a, b, and c 
above) of the function acquire the arguments of the function call 
as bindings. Evaluating a variable produces its binding as a 
value. For instance, if someplace in a function you evaluate the 
form: 

(addandmult 2 (+ 3 2) 6) 
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a, b f and c will have the bindings 2, 5, and 6 while the forms in 
the definition of addandmult are being evaluated. This is not 
unlike the subroutine parameter mechanism in other languages. It 
is different insofar as it specifies what value a variable has 
during "subroutine" execution. In PL/I or FORTRAN, a parameter 
is associated with a variable in the calling program, not a 
value, during subroutine execution. 

There are parameter variables, as used above, temporary 
variables, described below, and global variables . Regardless of 
the kind of variable, they- all have bindings (values), and 
evaluation of the variable produces that value. 



To summarize: 

I- Lisp programs are built of functions. 

2. Function definitions consist of the word "defun", the 
function's name, a parameter list, and a number of 
forms, which are to be sequentially evaluated at 
function call time, with a pair of parentheses around 

3.. The value of the last form in a function is the value 
returned by that function. 

4. Forms can be strings, numbers, variables, or calls to 
functions. Forms are evaluated to produce values, 
which are passed between" functions as arguments and 
results. 

5. Strings and numbers evaluate to themselves. 

6. Variables evaluate to the datum to which they are 
bound, which, for a parameter, is the corresponding 
argument to the containing function. 

7. Function calls contain the name of a function to call 
and forms that are evaluated to produce the arguments 
to the function. Function calls may produce side 
effects. Like any form, when a function call is 
evaluated, it produces a value. 
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PREDICATES 

Programming languages need conditional execution. In order 
to control _ conditional execution, you need things upon which to 
base a decision. Two data objects in the Lisp world correspond 
to truth and faisity, for the purposes of parts of the Lisp 
system that deal with conditions. A set of functions called 
predicates return these objects as values. For instance, a 
function called ">", invoked as: 

(> 4 6) 
returns the indicator of falsity, and when invoked as: 
(> 4 1) 

returns the indicator of truth. Predicates work just like other 
builtm and nonbuiltin functions, like print, addandmult, 
squareprint, and +. They take arguments, and produce a result. 
In the case of predicates, however, the result is not a string or 
a number, but an indication of truth or falsity. The result of a 
predicate can be used by the if special form (see below) to 
control the execution of a function. 

The following are some of the most useful Lisp predicates. 
In all of these examples, Al, A2, SI, 01, etc., stand for forms , 
whichmeans they can be 12, (+ 6 q) , (myfun 33 (- a b) )7^tc"! 
Al is a number, below, means that Al is some form which 
evaluates to a number, such as 3, (+6 2), or x49. if x49's vain* 
is maeea a number. ' " 

Predicate for Numbers 

Al and A2 are numbers: 
Predicate Example Returns TRUTH if ..., otherwise falsity. 



s 


(= 


Al 


A2) 


> 


(> 


Al 


A2) 


< 


(< 


Al 


A2) 



Al and A2 are the same number. 
Al is a bigger number than A2. 
Al is a smaller number than A2. 
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Predicates for Strings 

SI and S2 are strings: 

samepnamep 

(samepnamep SI S2) 

SI and S2 are strings of identical content, i.e., the 
"same string". This is the standard way to see if two 
strings are the same r as in (samepnamep test "-hold") 

alphalessp 

(alphalessp SI S2) 

SI. collates before S2 alphabetically, e.g., 
(alphalessp "Able"" "Baker") returns truth, but 
(alphalessp "Zeke" "Joe") does not. 

Predicates for Any Objects 

01 is some object, of perhaps unknown type (objects are 
discussed later) : 

eq (eq 01 02) 01 and 02 are the same symbol 

or the same cons. 

fixp (fixp 01) 01 is a number, as opposed to 

some other kind of object. 

stringp (stringp 01) 01 is a string, as opposed to 

anything else. 

symbolp (symbolp 01) 01 is a symbol, as opposed to 

anything else. 

null (null 01) 01 is not only a symbol, but 

the important and 
critical symbol named "nil". 



LISP SPECIAL FORMS 

A number of special forms in Lisp do not go by the simple 
rules given above. You have already seen one. The 
function-defining form, which begins with the word "defun", is 
not simply a function call with forms to produce the function's 
arguments. By all rights, a form like: 

(defun square (x) 
(* x x)) 

should evaluate, in order, to produce arguments for "defun": 
1. A variable named "square". 
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2, The form, (x), calling a function named "x" with no 
arguments. 

3. The form, (* x x), multiplying the value of a variable 
named "x" by. itself, 

This _ form should then pass these three values on to the def un 
function. This, however, is not what actually happens. 
Evaluating the defun form causes a function named square to be 
defined, whose parameter list and "body" are as given. Defun is 
a special form , and when Lisp sees "defun" as the function name 
in a form, it acts in a special way. In this case, Lisp defines 
a function built out of this form itself . The above is not a 
call to defun with arguments. It may seem unusual, but youlust 
have at least one such special form in order to have an operative 
Lisp system. 

The if Special Form 

A special form in the Multics Emacs Lisp environment, called 
it, controls conditional evaluation. An example of its use: 

(defun which-is-greater (first second) 
(if (> first second) 

(print "The first one is the greater.") 

else 

(if (> second first) 

(print "The second one is greater") 

else 

(print "They are equal"))) 

The syntax of if is as follows: 

(if <PREDICATE> 
<THEN-F0RM-1> 
<THEN-FORM-2> 

• • • 

<THEN-FORM-m> 
else 

<ELSE-F0RM-1> 
<ELSE-F0RM-2> 

• • • 

<ELSE-FORM-n> ) 

t _ Any number, including none, of THEN-FORMs can be supplied. 
Similarly, any number, including none, of the ELSE-FORMs can be 
given. If there are no ELSE-FORMs, then the keyword "else" may 
be omitted, too. 
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Note that all the forms in the if are not sequentially 
evaluated; the word else is not even intended to be a form. If 
all of the forms inside the if were evaluated, it would be 
useless, for evaluation would not be conditional. That is why if 
is a special form; there are special rules about how forms inside 
it are to be evaluated. The rule for all nonspecial forms is the 
same: you evaluate all the subforms sequentially to produce the 
arguments to the function. Each special form has its own rules. 

The if special form evaluates the PREDICATE: if it results 
in truth r the THEN-FORMs are sequentially evaluated, and the 
value of the last one is returned as the value of the if. 
Otherwise, the ELSE-FORMs are evaluated sequentially, and the 
value of the last returned. If there are none, the symbol nil 
(see below) is returned. 

There are two global' variables in Lisp, called "t" and 
"nil", whose bindings are always the truth and falsity 
indicators, respectively. Thus: 



(if t 



(print "Truth") 



else 

(print "Not so truth")) 

when evaluated, always prints "Truth". 

The actual object used as the indicator of falsity is the 
symbol named nil (see "Symbols" below). All predicates return 
this symbol to indicate falsity. The usual indicator of truth is 
the symbol named t; however, all special forms and functions that 
test predicates consider any object, other than nil, to be an 
indicator of truth. Thus, many functions return the symbol named 
nil. to indicate failure and some "good" value (not nil) to 
indicate success. 



The setq Special Form 

Variables acquire values by being parameters, and acquiring 
values at function call time. In addition, variable values can 
be changed by the special form setq : 

(defun adder-of-one (x) 

(print "The value of x is") 
(print x) 

(setq x (+ x 1) ) 
(print x)) 
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A setq form has the word " setq ", the name of a variable, and an 
inside form. The inside form is evaluated, and that value 
assigned to the variable. It is like an assignment statement in 
other languages. 

The do-forever and stop-doing Special Forms 

The construct for looping in the Emacs Lisp environment is 
also a special form, called do-forever : 

(do-forever 

(print "Yay Multics") 
(print "scitluM yaY" ) ) 

When evaluated, it prints these two sayings forever. The way you 
stop doing in a do-forever is to evaluate the stop-doing special 
form: 

(defun print-n-times (n) 
(do-forever 

(if (= n 0) (stop-doing)) 
(print "foo") 
(setq n (- n 1)))) 

This function, given a number as an argument, prints "foo" that 
many times. The " = " builtin function/predicate compares its two 
arguments, which must be numbers, and returns truth or falsity 
-depending on whether or not they are numerically equal. The 
arguments^to = are not n and 0, but rather, the numbers that are 
the bladings of n and 0. The number which is the binding of n is 
different each time around the loop? that is the point of the 
program. It is setq that changes the value of n each time 
around, as do-forever executes the loop. A do-forever form 
generally returns something useless (nil), unless you exit by 
saying (return 5) or (return nil), or (return a). In theliTter 
case, the value of the variable a is returned. 

The let Special Form 

You can acquire temporary variables via the let special 



form: 



(defun sumtimesdif (x y) 
(let ((sum (+ x y)) 
(dif (- x y))) 
(print "Sum times difference is ") 
(print (* sum dif)) 
(print "Sum squared is") 
(print (* sum sum)) ) ) 
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This function has two temporary variables, sum and dif, which are. 
initialized to the values of ( + x y) and (- x y) . The general 
syntax of let is: 

(let ((VAR1 VAL1) 
(VAR2 VAL2) 



(VARn VALn)) 

<F0RM1> 
<F0RM2> 

•r- •* »■ * •» •■ •» 

<FORMm> ) 



The temporary variables VAR1. ..VARn exist only within the 
let - They get the initial values of VAL1 through VALn, which are 
forms that will be evaluated. All the VALs are evaluated^ before 
any of their values are assigned to the VARs. Then, withall 
these temporary variables set up and initialized, each FORMi is 
evaluated sequentially, and the value of the last FORMi is 
returned by let. 

mt, _.._._ __j — — <?•— — -..: ~ 1 rc „—,«.- 



Another, less useful way of acquiring temporary variables is 
via the special form prog . Forms inside a prog are evaluated 
sequentially, like forms in a function definition. However, the 
first form in a prog is not really a form at all, but a list of 
temporary variables used in the prog, such as "(a b c)". That is 
why prog is a special form. The value returned by progis 
usually useless, unless (return...) is used to return something 
meaningful. 

Inside a prog, you can put labels , to use for go-to' s: 

(defun bar2 (x y) 

(prog () ;note the empty variable list 

(if (< x y)(go labl)) 
(print "X is not less than Y") 

(return nil) ;return "false" indication 
labl 

(print "so be it!") 

(return t))) ; return "true" indication 

In the special form £0, its operand (not argument) is a label to 
which to go, i.e., continue sequential evaluation of forms in the 
prog. Labels are rarely needed, due to the powerful if_ and 
do-forever constructs. 
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The or And and Special Forms , And not 

There are special forms for or-ing and and-ing predicate 
results: they are special because they stop evaluating their 
operands (from which arguments are produced) when they "know" 
their answer for certain: 

(if (and (not (= x 0) ) 

(> (// 10 x) 5)) 
(print "Quotient too large.")) 

The^ not function inverts truth and falsity. The double slash 
indicates division, because slash is the escape character in 
Lisp. 

The and does not attempt to evaluate the second form within 
it if the first produces falsity. This prevents an error that 
would result if_ an attempt were made to divide by zero. 
Sequential execution and stopping at an intermediate result are 
defined and useful features here, as opposed to the logical 
•operators of, say, PL/I. 

The progn , proql , and proq2 Special Forms 

Three more special forms are progn, progl, and prog2. To 
force sequential execution of forms and return the value of the 
last, use progn. For instance: 

(if (and (> x 3) 

(progn (print "Oh dear this is getting serious") 

{> y 5)) 
(print "Fatal difficulty"))) 

In the above, progn returns the value of its last form. Thus, 
the and tests whether x is greater than 3, and y is greater than 
5, before the "print" of "Fatal difficulty" is evaluated. The 
printing of "Oh dear..." occurs as part of the evaluation of the 
progn, but the and sees only the second value in the progn. The 
progn is used to force evaluation of the print form. 
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A progl is just like progn, except that it returns its first 
argument, evaluated, rather than its last. It must have at least 
two arguments. It is useful for saving some value that is 
subsequently going to be destroyed. The following form, when 
evaluated, interchanges the values of x and y: 



(setq x (progl y 

(setq y x))) 



the value of y is obtained here, 
and remembered as it is here. 
x is evaluated, and that value 
assigned, to y. The value of 
setq form is that value. 



In the above, however, the value of proql is that value of y as 
it was before it was assigned into y, and now the outer setq 
assigns that to x» A prog2 is an older form of progl and is 
similar, except it returns its second argument. 

SYMBOLS 

Another type of data object in Lisp is called the symbol . 
Symbols are named data objects kept in a registry of symbols (the 
obarray) , by Lisp. For current purposes, there is only one 
symbol nf an v name. S v mbols are used in Emacs to re n resent 
buffer names, and various quantities associated with buffers. 
Lisp uses symbols to keep track of functions, and internally to 
keep track of global variables. 

To use a symbol in a program, give the name (the printname ) 
of the symbol preceded by an apostrophe ('). For instance, the 
form; 

(setq x 'Brunhilde) 

assigns the symbol named Brunhilde to x. Note that this is 
different from: 

(setq x "Brunhilde") 
which assigns the string Brunhilde to x, and from: 

(setq x Brunhilde) 
which assigns the value of the variable Brunhilde to x. 
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LISP LISTS 

The final Lisp data type of importance in writing extensions 
is the cons (for construct), and the larger data type built out 
of it, the list . A cons is a block that relates to two (usually 
other) objects in the environment, known as its car and its cdr. 
The function cons, given two objects, produces a new cons, whose 
car and cdr, respectively, are the two objects given. For 
instance, if the variable x has a value of the string 
"Brunhilde", as above, then: 

{cons 7 x) 

produces a cons whose car is the number 7 and whose cdr is the 
string "Brunhilde", returning it as a value. The functions car 
and cdr can be used to obtain the car and cdr of a cons. If you 
set the variable c to the result of the form (cons 7 x) above, 
then: ' 

(car c) 

produces the number 7 as a value. 

Usually, you make larger and larger structures out of 
conses, by setting up conses whose car and cdr are more conses, 
and so forth, until you have a large enough structure to 
represent all the values you need. The resulting construction 
serves the same purpose as a PL/I structure: its various parts 
have meaning assigned by the programmer. 

The most common construction of conses is the list. A list 
is defined as a chain of conses, each of which has the next one 
in the chain as its cdr, except the last one, which has the 
symbol "nil" as its cdr. A list built in this way of n conses is 
called a list of n elements , the elements being the n objects 
that are the cars of the conses. The cons at the head of the 
list is identified as being "the list": its car is the first 
element in the list, its cdr is the cons whose car is the second 
element of the list, and so forth. To construct a list of the 
numbers 2, 4, 5, and 7, in that order, and set the variable b to 
it, you would need: 

(setq b (cons 2 (cons 4 (cons 5 (cons 7 nil))))) 

(Note that the variable "nil" is peculiar insofar as its value is 
always the symbol "nil", thus you need not say 'nil.) 
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A function that simplifies the writing of such forms, for 
constructing lists, builds lists directly and accepts any number 
of arguments. It produces the same result as the type of 
construction shown above. It is called "list": 

(setq b (list 2 4 5 7)) 

To get the third element of the list, once this form is 
evaluated, you could evaluate the form: 

(car (cdr (cdr b) ) ) 

(i.e.., the car of the cons that is the cdr of the cons that is 

the cdr of the cons that is the value of b). Again, there are 

Lisp functions to simplify such constructions. The above form is 
equivalent to: 

(caddr b) 

In general, for up to 4 cars and cdrs deep, total, functions like 
cadr r cdar, caddr, cadar, and so forth, are provided (up through 
caaaar and cddddr) . The first four elements of a list are gotten 
by car, cadr, caddr, and cadddr (it is a good exercise to work 

i_i.i£Lt« i«U4VU^U €U*%-* v ^ U 1* i. JF WAljr LUIS AS UilCT K* GL O G ) • 

When lists are printed out by Lisp, they are represented as 
a pair of parentheses around the printed representations of all 
of the elements, in sequence, separated by spaces. Thus, if Lisp 
printed out the list that was b's value above, it would appear: 

(2 4 5 7) 

A cons whose cdr is the symbol nil can always be viewed as a list 
of one item, and is so printed out by Lisp, unless it is in the 
process of printing a larger list of which the cons at issue is a 
chain-link. A cons whose cdr is neither nil nor another cons is 
printed with a dot preceding the cdr. Thus: 

(cons 'a 'b) => (a . b) 

(cons 'a nil) => (a) ;a list of one element 

(cons 'a (cons 'b 'c)) => (a b . c) 

(cons 'a (cons 'b nil)) => (a b) ;list of two elements 

(cons 'a (cons (cons 'b 'c)(cons 'd nil))) 

=> (a (b . c) d) ;list of three elements 



2-14 CJ52-01 



Lists can be put into programs, by quoting them, as symbols 
are quoted: 

(setq bl '{this is (a list) (of lists))) 



the car or cdr of an 



Two functions are provided to redefine 
existing cons. They can be very dangerous if misused, especially 
if they alter a list as in the form above, which is written into 
a program as a constant. The rplaca function (replace car) and 
the rplacd function (replace cdr) each take two arguments. The 
first is the cons that is to be altered, and the second is the 
new car or new cdr, respectively. The returned value is the 
itself. 



cons 



Other list Primitives 



A variant of list, list*, 
argument becomes the cdr 
list*, given n arguments 
n-1 arguments; the same 
instead of the last cons 
is made its cdr. Thus, 



is just like list except its last 
of the last cons constructed. That is, 
(n > 2), constructs a list of its first 
as list given those n-1 arguments, but 
having nil as its cdr, the nth argument 



(list* 2 3 5 7) => (2 3 5 . 7) 

Note that: 



(list 2 3 5 7) 






(2 
(2 



7 
7) 



nil) 



and: 



(list 2 3 5) 



=> (2 
=> (2 



5 
5) 



nil) 



Another function for manipulating Lisp lists is append . It 
accepts any number of arguments, each of which is a list of zero 
or more elements, and constructs a list containing all the 
elements of all the lists, in order. Thus, 



=> 



(a 






' (able baker) 
(a (b) c able baker 2 3) 






3)) 
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The append function constructs a new list. A "destructive" 
form of append, called nconc , creates the result it returns by 
"patching" its input arguments to create a longer list, i.e., it 
changes the cdr of the last cons of each input list to be the 
first cons of the next list. The nconc function must be used 
with caution; e.g., it is always an error to give a constant 
(i.e., a quoted piece of list structure) as an argument to nconc. 

Another Lisp function for dealing with Lisp lists is 
reverse . Giverr a list, it returns a list with the same elements 
as the input list but in reverse order- The nreverse function is 
similar to reverse but, like* nconc, does its work by 
destructively modifying the input list- 

A superlative method for writing code that builds list 
structure is provided by the Lisp "backquote" facility. The 
backquote facility is described in Appendix A. 

LISP MACROS 

List Structure as Code 

One of the most powerful features of Lisp is the ability of 
Lisp programs to manipulate Lisp programs easily. The internal 
representation of Lisp programs during compilation and debugging 
is that of Lisp lists. You may have noticed that Lisp lists 
strongly resemble pieces of Lisp programs. For example, the 
form: 

(setq x (■•- y z)) 

is simply a printed representation of a list of three elements: 
the symbol setq, the symbol x, and the list (itself of three 
elements) of the symbols +, y, and z. Thus, a form is simply a 
piece of Lisp structure that is intended to be evaluated. In 
fact,, the eval function does precisely that; given a piece of 
list structure, i.e., a form, as an argument, eval evaluates it 
and returns the value of that form. Note how symbols represent 
both functions and variables, depending upon where they appear in 
forms. Symbols have bindings , which represent the binding of the 
variable represented by the symbol, and functional properties via 
which the associated function or code for a special form can be 
found. Thus, if the symbol (and thus variable) f is bound to: 

( e «a ^ it v / 4- tr 7^ ^ 

and y is bound to 3, and z is bound to 4, then evaluation of the 
symbol (variable) f would produce: 
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(setq x ■ (+ y z)) 

a list of three elements. Evaluation of: 

(eval f) 

would pass that list of three elements as an argument to eval, 
causing its evaluation, which would cause x to have a binding of 
7 and return 7 as a result. 

In some sense, the basic action of Lisp is that of 
evaluation. However, user programs, other than Lisp debuggers or 
interpreters, rarely use the eval function. If you think you 
have to use eval (except sometimes in macros; see below), you are 
probably having difficulty with the concept of evaluation. 

Using Lisp Macros 

Lisp macros, allow a user to specify the translation of code 
with a syntax of his choosing into code representing the meaning 
he assigns to that syntax. A macro is defined just like a 
function, except that the word (symbol) "macro" (without 
quotation marks) appears between the function name and the 
parameter list. For instance: 

(defun t-return macro (x) 

(append (cons 'progn (cdr x)) 
'(t))) 

defines a macro named t-return. When the compiler or interpreter 
sees a form whose car (i.e., where the function name belongs) is 
a symbol that has a macro definition (as above) associated with 
it, it passes the entire form to the macro as an argument , runs 
the macro (i.e., calls it with that argument), and reconsiders 
the result as if it were encountered in place of the original 
form. Thus, if a program contains a form: 

(and (> x 15) 

(t-return (setq flag nil)) 
(return x)) 

at the time this form is evaluated or compiled, in place of the 
second form, the form: 

(progn (setq flag nil) t) 

will be evaluated or compiled. This is because t-return has been 
defined as a macro; the function defined by t-return, when called 
with: 

(t-return (setq flag nil)) 
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as an argument, produces: 

(progn (setq flag nil) t) 

as a value. The fact that t-return has been defined as a macro 
causes the compiler to invoke t-return to translate the t-return 
form into its meaning , so that can be compiled or evaluated in 
its place. 

The backquote? facility (see Appendix A) is extremely useful 
for defining macros. Using backquote, you could define the macro 
above asr 

(de-fun t-return macro (x) 

"* (progn ,@(cdr x) t) ) 

See Appendix A for another example of a macro. Additional 
examples of macro definitions are contained in the 
e-macros.incl.lisp include file (after the first two pages if you 
dprint it) ► Bear in mind when studying them, however, that they 
reference internal Emacs variables and functions or embed certain 
knowledge that they are designed to hide. 

PRINTED REPRESENTATION OF LISP OBJECTS 

Lisp objects exist in the Lisp or Emacs environment. They 
relate to each other, and they denote each other. The calling of 
functions, whether built-in, Emacs-provided, or user-provided, 
creates new objects and changes the relationships among existing 
objects. 

Objects are symbols, conses, and strings in the Lisp 
environment; they are not parentheses and words on paper or in a 
buffer. However, you often need to obtain the printed 
representation of a Lisp object or generate a Lisp object based 
upon its printed representation. This is most commonly the case 
with numbers; in Emacs, the decimal-rep function obtains the 
printed representation of a decimal number as a string. 

The Lisp explode function creates a list of the 
single-character symbols representing the printed representation 
of the argument that was given. Passing such a list to the Lisp 
maknam primitive produces a symbol whose printname is that 
printed representation; that symbol is as good as a string for 
any purpose in Lisp or Emacs. Instead of maknam, the Emacs 

— .»»,-. 1 .*__-**- a T* a <t- s r->»--Jmi+-iTT«» r~?m Ka neai) h r\ r\rr\Al^r• a a ef rinn and ntau 

CI WW AY LaCCllOCC Wt-LUIiUAVG WU14 *rf^ wSwm WW £**. v« s*«— w u w w -*- — *• -g *»..*— .••_ j 

be more efficient. 
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The conversion of numbers by explode is controlled by two 
global variables, base and *nopoint: base is the output radix, 
which is eight by default, indicating octal; *nopoint is nil, 
indicating that numbers are to be converted with a decimal point 
if base happens to be ten. Thus: 

(let ( (base 10.) 

(*nopoint t) ) 
(apply-catenate (explode x))) 

obtains the printed representation of the value of x, with 
numbers converted as decimal, without decimal points. 

read - f rom - strinq 

The Lisp read-f rom-string function constructs Lisp objects 
from strings (or symbols with a meaningful printname). Given a 
valid printed representation of a Lisp object, read-f rom-string 
recursively constructs (for lists), creates (for numbers or 
strings), or finds on the obarray (for symbols) the appropriate 
objects. Thus, if x is bound to the string "(a b c) n , the form: 

(read-f rom-string x) 

would produce as a value a list of the three symbols a, b, and c. 
In converting numbers with read-f rom-string, integers followed by 
a decimal point (e.g., 6., 27., and 259., but not 5.0, which is 
floating point) are converted as decimal. Unpointed integers are 
converted as ^per the value (as radix) of the ibase global 
variable, which is normally eight. Thus, 

(let ((ibase 10.)) 

(read-f rom-string x)) 

converts the value of x with all unpointed numbers assumed 
decimal. ,- 
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SECTION 3 



WRITING EMACS EXTENSIONS 



Writing extensions is basically a matter of building new | 

functions out of the standard functions provided in the Emacs | 

Lisp environment. These new functions can be hooked up to keys | 

in the same fashion as standard Emacs functions, via the set-key | 

and set-permanent-key functions. | 

Many useful extensions can be made simply by stringing J 
together groups of Emacs requests. For instance, to go to the | 
beginning of a line, delete all whitespace there, go to the end 
of the line, do the same, and then return to the beginning of the 
line, you could type: 

A A ESC \ A E ESC \ A A 

Alternatively, you could write a function, called shave-line 
here, to do the same: 

(defun shave-line () ; keystroke functions take no args. 



(go-to-beginning-of-line) 
( dele te-white-s ides) 
(go-to-end-of-line) 
(delete-white-sides) 
(go-to-beginning-of-line) ) 



function hooked to A A key | 

function hooked to ESC \ key | 

function hooked to A E key | 

ESC \ | 

A A J 



Write this function into a file. When in Emacs, type ESC X 
loadfile PATHNAME CR, to load it in as code. Then hook it up, 
perhaps by typing (when typing this, type the caret key for A , | 
not the control key): | 

ESC X set-key A XA shave-line CR 

Thereafter, hitting A XA (control X A) causes your new shave-line | 
function to be run. | 
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I If you want a function that goes to the beginning of a line 

j and deletes all words that start with "foo" from the beginning of 

j the line, for example, you need to use Emacs conditionals and 

| variables. 

(%include e-macros) 

(defun foodeleter () 

(go-to-beginning-of-line) 
(do-forever 

(Lf (looking-at "foo") 

(delete-white-sides) 
else (stop-doing)))) 

The (%include e-macros) must be at the beginning of any file that 
uses the Emacs environment Lisp macros. The e-macros. incl. lisp 
file should be in your "translator" search path in order to do 
any Emacs extension development work. 

What this function does in essence is type A A, and as long 
as the first three characters on the line are "foo", does an ESC 
D, followed by ESC \ to remove the whitespace after the word. 
When the first three characters are no longer "foo", it returns. 
The: "looking-at" is an Emacs predicate (to be described in detail 
below) that tests whether a given string is to the right of the 
current "cursor". For this function and any others that you 
write, you could set a key as described above ( A XA for 
shave-line) . 

The code for the foodeleter makes no mention of printing, 
output, or displays because it does not need to. The screen or 
printing terminal is managed automatically by the Emacs 
redisplay. The display need never be thought about in coding 
Emacs extensions. 



USING EMACS REQUESTS IN EXTENSION CODING 

Many of the Emacs requests can and should be used in coding 
extensions, for example, go-to-end-of-line, forward-char, 
go-to-beginning-of-buf f er , delete-word and skip-over-indentation. 
Some requests, however, should not be used in extension code. 
For example, if you want to search for some string, you do not 
want to invoke string-search ( A S), since that prompts the user in 
the minibuffer for a search string. The following table lists 

SOtne imDOrtsnt - kovctrolfP rpnn»«hs uhosa rnmmanrl namoc yom eh«!'l^ 

not use and gives alternative functions to use. 
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KEY DO NOT USE USE INSTEAD 

A N next-line-command next-line 

The next-line-command function is unnecessarily 
expensive in considering screen position, and handles 
numeric arguments. The next-line function always goes 
to the beginning of the next line. 

A P prev-line-command prev-line 

Same reasons as above. The prev-line function always 
goes to the beginning of the previous line. 

A K kill-lines kill-to-end-of-line 

delete-char (at eol) 
The kill-lines function is complex, has many cases, and 
handles numeric arguments. 

A S string-search forward-search 

The forward-search function takes a string as a Lisp 
argument, does not prompt, moves the cursor if the 
search succeeds, and returns truth or falsity to 
indicate result. 

A R reverse-string-search reverse-search 
Same as A S. 

A X A R read-file read-in-file 

The read-in-file function takes a Lisp argument for 



*x*w 



A 



pathname, does not prompt. 

urif o-f i la u>>i*<s./Mii— t:t. 

Same as A X A R. 



w wipe-region wipe-point-mark 
Use local marks, see below. 

ESC W copy-region point-mark-to-string 

does not require modifying the user-visible mark or the 
kill stack. 

ESC / regexp-search-command regexp-search 

Same issues as A S. Takes a Lisp argument, no slashes. 
Returns falsity if not found or moves cursor to after 
and returns mark to before, matched string. Be careful 
to release this mark (see below). 

A XB select-buffer go-to-or-create-buf fer 
Takes an argument, does not prompt. 

A X A F find-file f ind-f ile-subr 

Takes an argument, does not prompt. 
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A L. redi splay-command full-redisplay 

redi splay-cur rent -window- relative 
Two separate functions, less dealing with numeric 
arguments. 

Requests that accept a positive numeric argument as meaning 
repeat that number of times, e.g., A B, A D, A F, ESC B, ESC D, ESC 
F, #., ESC #, etc., are acceptable in extensions; they do not 
inspect their arguments* They are invoked multiple times by the 
Emacs listener if appropriate- Requests whose names include the 
word, "command" - are usually not intended to be used in code. 

The value of a numeric argument, e.g., 5 in ESC 5 A B, is 
available as the binding; of the global variable "numarg"; if no 
numeric argument is given, this variable is set to the symbol 
"nil" (not to be confused with the global variable nil, whose 
binding is, the symbol nil), which is the representation of 
falsity. 

The normal printing characters are bound to the self-insert 
function, which inserts the last physical character typed at the 
current point in the buffer. This is clearly unusable' from code, 
if your desire is to insert text into the buffer. For this 
purpose, the Emacs environment provides the insert-string 
function, whose argument is a string to be inserted into the 
buffer at the cursor. As in typing in text manually, the cursor 
is left after the inserted text: 

(defun make-a-point () 

( go-to-beg inn ing-of- line) 
(insert-string "CASE IN POINT: ")) 

This make-a-point function, when invoked, goes to the 
beginning of the line, and inserts the string "CASE IN POINT: " 
in the buffer. The cursor is left after the inserted string. 

As used here, phrases like, "the cursor is moved around" or 
"a string is inserted" in a function, do not imply that the user 
watching the screen can see all these things happen. No action 
on the screen occurs until the entire function has finished 
running, at which time the screen is updated all at once, showing 
the cumulative effect of what has happened, regardless of how it 
happened. 
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MARKS AND THEIR MANAGEMENT 

_ Like the cursor, a mark is a conceptual pointer to the 
position between two characters in the current buffer. Marks 
remain _ between these two characters regardless of other 
insertions or deletions in the same buffer, even on the same line 
as the mark. Marks are valuable because regions of text in the 
buffer are specified as the extent between the current conceptual 
cursor, (the point), and a given mark. Marks are a type of data 
object in the Emacs Lisp environment, like strings, numbers, and 
symbols. The value of any variable can be made to be a mark. 
The value of several variables might even be the same mark. The 
words "the-mark" used in Emacs descriptions designate one mark 
that is the value of a global variable that many supplied 
functions know about. Emacs functions use many temporary marks. 

32l£ set-mark , release-mark and wipe-point-mark Functions 

The set-mark function creates a new mark, which points to 
the current point in the current buffer. It stays around, and is 
updated by the editor, any time text is inserted or deleted in 
this buffer. This is expensive, so you must take care to 
discard, or release marks when you are done using them. This is 
done by giving them to the release-mark function. An example of 
a function which deletes three words and everything between them 
follows: 

(defun delete-three-words {) 

(let ((temp-mark (set-mark))) rmake a mark in 

;a temp var. 
(do-times 3 (forward-word)) ;3 words forward 
(wipe-point-mark temp-mark) ;wipe out the stuff 



( release-mark temp-mark ) ) ) 



; between point and 
; where point was. 



The variable temp-mark is set to a mark representing the point at 
the time delete-three-words is entered. The B do-times n is a 
special form that repeats the evaluation of one or more forms a 
given number of times. Its syntax is: 

(do-times <HOWMANY> <F0RM1> <F0RM2> .. <FORMn>) 

The wipe-point-mark is a function that, given a mark, takes all 
the text between point at the time it is invoked and that mark 
(i.e., point at the time that mark was created) and deletes it 
from the buffer. It is pushed onto the kill ring, so that A Y can 
be used to retrieve it. After the computation, the mark is 
treed, (for better performance). 
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The with-mark Special Form 

The sequence of setting a mark, using it, and releasing it 
is so common that a special construct in the Emacs Lisp 
environment is provided that takes care of all of this, including 
the creation of a temporary variable, so no prog or let is 
needed. It is called with-mark . The delete-three-words 
function, rewritten to use it, looks like this: 

(defun delete-three-words () 

(with-mark nr ;m is usually used for the name of a mark 
(do-times 3 (forward-word)) 
(wipe^point-mark m) ) ) 

The syntax of the with-mark construct is: 

(with-mark <MARKNAME> 
<FORMl> 
<F0RM2> 

* *■ •■ 

<FORMn> ) 

It means: "Where I am now, call that <MARKNAME>. Evaluate the 
forms <F0RM1> to <FORMn>, sequentially, returning the value of 
the last one as a value. Before returning anything, however, 
free the. mark I made." 



Marks allow you to return easily to where you were at the 
time you started something. The following function truncates a 
line longer than 50 print positions, and handles backspaces and 
tabs properly: 



(defun trunc-50 () 
(with-mark m 

(go-to-end-of-line) 
(if (> (cur-hpos) 50.) 

(go-to-hpos 50.) 
(kill-to-end-of-line) ) 
(go-to-mark m) ) ) 



; remember where you started 

;dot is for decimal 
;default is octal 

;what A K does at not e.o.l. 
; return to where you were 
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instead be: 

(if (go-to-hpos 50.) 

(kill-to-end-of-line)) 

The ^{go-to-mark m}" above tells the editor to move the 
current point in this buffer to the point where it was at the 
time the mark called "m" was created. 

The save-excursion Special Form "'' 

Although moving the editor's point to previously saved marks 
is extremely useful, you often use marks simply to return to the 
place where you were before you began a sequence of requests. 
Tftis case is so common that a special mechanism is provided just 
for this: it is called save-excursion, and it takes care of all 
the problems of temporary variables and releasing the mark when 
done. The sample function trunc-50 recoded to use save-excursion 
looks like this: 

(defun trunc-50 () 

(save-excursion 

(go-to-end-of-line) 
(if (> (cur-hpos) 50.) 
(go-to-hpos 50.) 
(kill-to-end-of-line) ) ) ) 

The save-excursion special form does the following: remembers 
where you are, via a mark saved in an internal variable, 
evaluates all of the forms within the save-excursion, and returns 
as a value the value of the last one. Before returning anything 
however, it moves the editor point back to where it was when the 
save-excursion was first entered, and releases the mark used to 
remember this place. 

If point were at print position 75 at the time trunc-50 was 
caned, it winds up at position 50, even though the mark to which 
it wants to return points to what was at position 75. No error 
is indicated, or has occurred. Marks remain even if characters 
to the right or left of them are deleted. 

The save- excursion -on- error Special Form i 

The special form, save-excursion-on-error, is used in the I 
same way as save-excursion. It returns to the original point I 
only if an error occurs while executing the functions. j 
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KILLING, SAVING, AND MODIFYING IN EXTENSION CODE 

Most Emacs functions that delete text from the buffer save 
the text on the kill ring. Functions that you define that use 
these standard functions (such as delete-three-words, above), 
therefore, also save the deleted text. 

To prevent deleted text from being saved, wrap the code, that 
will delete text in the without-saving special form. For 
examples 

(without-saving (wipe-point-mark m) ) 

deletes all the text between the current point and the position 
designated by the mark m without saving it on the kill ring. Any 
text deleted by an internal deletion primitive while the code 
contained within a without-saving special form is executing will 
not be pushed onto the kill ring. 

The without-modifying special form is similar to 
without-saving. It is used to enclose code that deliberately 
modifies read-only buffers, such as those used by the directory 
and buffer editors. For example: 

(without-modifying 

(go-to-beginning-of-line) 
(delete-char) 
(insert-string "X")) 

might appear in a menu-type editing subsystem within Emacs to 
change the space at the beginning of some line to an X when the 
user selects an object for deletion. 

Text can be explicitly pushed onto the kill ring by _ the 
killsave-string function. It takes a single argument, which is a 
Lisp string or symbol, and pushes it in the usual way onto the 
top of the kill ring. 



2/83 3-8 CJ52-01A 



Other functions which interface to the kill ring include 
kill-ring-top, kill-pop, and rotate-kill-ring. The kill-ring-top 
function returns the first item on the kill ring (as does A Y}. 
The kill-pop function returns, the first item on the kill ring and 
rotates the kill ring (as does ESC Y) . The first item becomes 
the last item, the second item becomes the first item, and so on. 
The rotate-kill-ring function just rotates the kill ring. 

CLEANUP HANDLERS 

You may have wondered, in the previous section, what happens 
if an extension encounters an error while executing, and never 
gets to release a mark it has set. When errors occur (for 
example, moving past the end of the buffer), Emacs aborts 
execution of request functions, returns to its listener, and 
beeps (as when a A G is performed). 
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The unwind-protect Special Form 

Since the releasing of marks is important, a facility like a 
cleanup-handler is needed to make sure that marks get released 
when code is aborted. There is such a facility in Lisp that is 
useful for many other things, too: save-excursion returns the 
cursor to the point at which it found it if aborted through; 
save-excursion-buf fer returns to the buffer where it found the 
editor if aborted through; all the mark-handling forms release 
their mark, and so forth. These Emacs-environment primitives use 
the cleanup-handler facility internally, so you need not worry 
about cleanup-handlers if you use them. However, occasionally 
(see the code for columnating the Emacs wall chart, for example) 
you must use cleanup-handlers explicitly. The Lisp form 
unwind-protect is the primitive cleanup-handler. Its syntax is: 

(unwind-protect 

<SUBJECTFORM> 

<CLEANUPFORMl> 

<CLEANUPFORM2> 

• • • 

<CLEANUPFORMn>) 

The <SUBJECTFORM> is evaluated, and then <CLEANDPFORMl> to 
<CLEANUPFORMn> (any number of cleanup forms are permissible), and 
the value of the <SUBJECTFORM> returned. So far, unwind-protect 
is much like prog2 or progn. The difference, however, is that 
<CLEANUPF0RM1> to <CLEANUPFORMn> are executed even if the 
execution of <SUBJECTFORM> fails and aborts. Similarly, the 
cleanup forms are executed even if things like a return from a 
prog inside the <SUBJECTFORM> causes its = execution to terminate 
prematurely. 

Thus, the cleanup forms are executed after every termination 
of the <SDBJECTFORM> , whether normal or abnormal. The following 
use of unwind-protect (which could be done in simpler ways, but 
is here for illustrative purposes) performs "complex-function", 
and returns the cursor to the beginning of the buffer, even if 
"complex-function" explodes: 

(unwind-protect 

(complex-function) 
(go-to-beginning-of -buffer) ) 

If you want more than one <SUBJECTFORM> , you should use progn to 
encompass them, and make your <SUBJECTFORM> this progn. 

Unlike Multics PL/I cleanup handlers, unwind-protect cleanup 
forms are executed upon normal termination of the subject form, 
too. 
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I The protect Special Form 



The e-macros special form, protect, can be used in place of 
unwind-protect. Its syntax is: 

(protect FORM! F0RM2 FORM3 F0RM4... 

talways CLEANUP1 CLEANUP2.. . 
Stsuccess SUCCESS1 SUCCESS2.... 
^failure FAILURE! FAILURE2 ......) 



wnerer 

FORMi 

CLEANUP i 
SUCCESSi 
FAILUREi 



are forms to be evaluated. 



are forms to be evaluated after the FORMs, whether or 
not an error occurs in evaluating the FORMs. 



are forms to be evaluated only if no errors occur in 
evaluating the FORMs. 



are forms to be evaluated only if an error does occur 
in evaluating the FORMs. 



Any of the clauses &always, &success, or tfailure can be omitted. 
Forms that were written using unwind-protect, e.g., 

(unwind-protect (progn FORMI FORM2...) 

CLEANUP! CLEANUP2 . . . ) 



j can now be written using protect as follows: 

| (protect FORMI FORM2. . .Salways CLEANUP! CLEANUP2...) 



USEFUL PREDICATES 

The following predicates in the Emacs environment are basic 
to all extension-writing; they are used to test various 
hypotheses about point, marks, and the buffer: 



(eolp) 

text line riaht before the newline character. 



ir^/3 /*\ -f 
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(bolp) 

Beginning of line predicate. True if point is at the 
start of a text line, either before the first character 
of the buffer, or after a newline. 

(f irstlinep) 

First line predicate. True if point is on the first 
text line of the buffer. 

(lastlinep) 

Last line predicate. True if on last buffer line, 
which is the line after the last newline character, if 
there is one. 



(at-beginning-of -buffer) 

True if point is right before the first character 
the buffer. 



in 



( a t-end-of -buffer) 

True if point is right before the newline on the last 
line of the buffer. You cannot go past it. 

(looking-at <STRING-VALUE>) 

True if <STRING-VALUE> appears in the buffer 
immediately to the right of point. Restriction: 
<STRING-VALUE> can not contain a newline character, 
except as its last character. 



(at-white-char) 
True if th 
newline, or tab. 



True if the character to the ricrht- nf nrtinf 4c = en 9> « 



(point>markp <MARK>) 

True if the current point is further in the buffer than 
the position defined by <MARK~ This is expensive, and 
should not be used casually in loops. 

(mark -reached <MARK>) 

True if the current point is up to or beyond <MARK> in 
the buffer. Intended for use in controlling 
character-by-character loops; it expects that point 
starts to the left of <MARK> and moves toward it. The 
function (order-mark-last <MARK>) can be used to switch 
point and mark if needed at the start of such loops. 
Does not terminate unless executed with mark and point 
on same line. 

(mark-at-current-point-p <MARK>) 

True if the mark <MARK> represents the same position as 
the. current point. 
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(mark-on-current-line-p <MARK>) 

True if: the mark <MARK> represents a position on the 
same line as the current point. 

(mark-same-line-p <MARK1> <MARK2>) 

True if two marks that are arguments represent 
positions on the same line. 

(line-is-blank) 

True if current line is all blanks: or empty. 

( empty-buf fer-p <BUFFER-SYMBOL> ) 

xcUe ll. tne out tec mencitieti oy , «ouErD«-3inoujj' ,r xa 

empty. The form (empty-buf fer-p current-buffer) can be 
used to test the emptiness of the current buffer. See 
below for a discussion of buffer symbols. 

(at <QUOTED-CHARACTER> ) 

True if the character given, e.g., (at "$"), appears in 
the buffer immediately to the right of point. This is 
more efficient than looking-at for single characters. 
Note that: 

(at " 
n ) 

is equivalent to (eolp) . Use the latter. (See also 
if-at. ) 

( bac k -a t <QUOTED-CH ARACTER> ) 

Same as at, but deals with the character to the left of 
the current point. See also if-back-at. 

(null-stringp <STRING-VALUE>) 

True if its argument is a zero-length string or a 
symbol with the zero-length printname. 

(yesp <STRING-VALUE>) 

Asks the user a yes-or-no question in the minibuffer, 
namely, <STRING VALUE>; accepts yes, y, no, or n as 
answers and returns true if response is affirmative. 
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This function that trims from the left (ltrims) all the 
lines in the buffer demonstrates the use of these predicates: 

(defun ltrim-all-lines () 

(save-excursion ;be polite, restore ooint 

( go- to-beginning-of -buffer) 

(do-forever ;loop on lines thru buffer 

(do-forever ;loop thru chars on line 

(if (eolp) (stop-doing) ) ;stop at eol. 
(if (at-white-char) (delete-char) ;do the work 
else (stop-doing))) ;non-white char, next line 
(if (lastlinep) (stop-doing)), -quit when did last line 
(next-line)))) ;leaves you at b.o.l. 

WHITESPACE MANAGEMENT 

Neatly formatted editor output and displays, as well as 
program and document formatting, require good whitespace 
management. The following functions exist to deal with 
whitespace: 

skip-over-whitespace 

Takes no arguments. Moves point forward over all tabs, 
blanks, and newlines until a non-white character or the 
end of the buffer is reached. 

skip-back-whitespace 

Takes no arguments. Moves point backward over all 
tabs, newlines, and blanks until the character to the 
left of point is none of these, or the beginning of the 
buffer is reached. 

skip-to-whitespace 

Moves forward until character to right of point is tab, 
blank, or newline. Since last character in buffer must 
be a newline, there is no special end condition.. 

skip-back-to-whitespace 

Moves backward until the character to the left of point 
is a tab, blank, or newline, or the beginning of the 
buffer is reached. 

delete-white-sides 

Deletes leading or trailing blanks from anything, or 
deletes space between words. 

skip-over-whitespace- in-line 

Same as skip-over-whitespace, but stops before the 
newline character at the end of the line (i.e., stops 
at the end of the line) if it gets that far. 
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skip-back-whitespace-in-line 

Same as skip-back-whitespace, but does not proceed 
backward beyond the beginning of the line. 

You often need to generate whitespace to reach a given 
horizontal position (column), for tabbing and page layouts. The 
function whitespace-to-hpos performs this service; it generates 
tabs and spaces as appropriate, moving point until the horizontal 
position that is its. argument is. reached* The following function 
moves: all lines: in the buffer seven spaces over, regardless of 
their original indentation, with, the right amount of tabs and 
spaces : 

(defun move-over-7 () 
( save-excursion 
(go-to-beginning-of-buf fer) ;all do-for-all-lines 
(do-forever ;start like this. 

(skip-over-indentation) ;This is ESC M 
(let ( (hpos (cur-hpos))) 

;let hpos be the curr. pos. 
(delete-white-sides) 

;close up all original space 
(whitespace-to-hpos ( + hpos 7))) 

;make just enough 
(if (lastlinep) (stop-doing) ) 
(next-line) ) ) ) 

A related need is to space to a given position, leaving a 
single space if you are already there or beyond. This is useful 
for producing columnar output where overlength fields must be 
separated (as A X A B does in its local display)^ The 
whitespace-to-hpos does not do this; it stops if it is far 
enough. However, format-to-col takes a single argument, a 
horizontal position to be spaced to. If the current point is 
already that far, it inserts a space. 

EXTRACTING TEXT FROM THE BUFFER 

The function point-mark-to-string gets a Lisp string whose 
value is the string of characters between point and the mark that 
is its argument. To demonstrate, a function that finds a 
vertical bar (|) on a line, deletes it, and swaps the two 
line-halves around it is defined below. For instance, the line: 

An Indian with a zebra | never trips in the snow 

comes outs 

never trips in the snowAn Indian with a zebra 
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The function is: 



(defun swap-around-bar () 

(go-to-beginning-of-line) 
(if (not (forward-search-in-line " | n ") ) 
(display-error "Hey, there is no " 
(rubout-char) 

(with-mark m ;m 

(go-to-end-of-line) 
(let ((temp (point-mark-to-string 



. ; check for one" 

1 • I ) 

;what # does 
in middle of line 



m))) 



J get 
;middle 
;to end 

(without-saving (wipe-point-mark m)) 

(go-to-beginning-of-line) 

(insert-string temp)))) ;p U t in text 



The forward-sea 
that it indicate 
the current 1 
display-error le 
stops the execut 
command level ( 
for some strin 
reverse-search- i 
similar in their 



rch-in-line is 
s failure if it 
ine. If 
ts you know 
ion of this 
see below) . 
g only in 
n-line, and 



just like forward-search, except 

cannot find its search string in 

the vertical bar is not found, 

and does a command-quit, ( A G), which 

function, at once and returns to Emacs 

This is useful by itself to search 

a given line. There is also a 

a- regexp-search-in-line, which are 



relation to A R and ESC /. 



TALKING TO THE USER 



xou cannot use tne Lisp I/O system to print out messages 
and/or query the user. The Emacs redisplay manages the screen 



itself, entirely. Thus, you can not use* "print", or 
other Lisp functions that you may be familiar with. 



'read' 



or 



A function called minibuf fer-print prints all the messages 
that Emacs outputs in the minibuf fer screen area. It takes any 
number of arguments, which must be strings. The function 
decimal-rep is provided to convert numbers into strings for 
inserting them in the buffer or handing them to display-error. 
The following function counts the number of As in the current 
line: 



(defun a-counter () 
(let ((n 0)) 



(save-excursion 
(go-to-beginning-of-line) 
(do-forever 
(if (not (forward-search-in-line "A")) 

(minibuffer-print "Found " (decimal-rep n) 
(stop-doing)) 
(setq n (+ 1 n))))) ;count them. 



; initial count 
;why not? 



'As.") 
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The forward-search-in-line leaves the point to the right of 
what it finds (like A S), so that it does not find the same 
occurrence the next time. 



To prompt the user for input in the minibuffer, use the 
function minibuf f er-response. It takes one, two, or three 
arguments. The first argument is the prompting string. The 
second is the character to be used to terminate minibuffer input. 
It can be either ESC or NL; if not supplied, NL is the default. 
If the value of ESC is: used, minibuffer input terminates on an 
ESC. rf the value of NL is used (NL, not CR) , minibuffer input 
terminates on a carriage- return. The third argument, when used, 
is a string to be inserted as the user's response. The. user can 
edit this string.. Thus: 

(minibuf f er-response "Type new division name: ") 

returns the user's response to this question when he terminates 
it with a carriage return. The value of minibuf f er-response is a 
Lisp string. The carriage return does not appear in it, nor does 
the prompt.. 

The minibuf fer-response function sets a variable called 

last-minibuf fer-response. If the ESC X opt 

remember-empty-response option is set off (it is on by default), 

last-minibuffer-reponse is not set to blank when a blank response 
is given. 

To display an error message in the minibuffer and then abort 
execution of an extension, i.e., execute a command-quit ( A G), use 
display-error. The display-error is like minibuf fer-print, 
except that it does not return, but aborts to Emacs top level 
immediately after printing its error message in the minibuffer. 
Like minibuf fer-print , it takes any number of string arguments. 

| # You can clear out the entire minibuffer with the 
| minibuf fer-clear-all function. It takes no arguments. 
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Message Printing Functions 

Messages printed by minibuf f er-print are 
keyboard macro execution, just as search 
displayed, and other gratuitous messages are 
following set of functions describes the 
message-printing: 



suppressed during 

strings are not 

suppressed. The 

repertoire of 



display-error 

Prints a message 
top level. It 
printing. 



in the minibuffer and 
is intended for use 



aborts to editor 
in error message 



display-error-noabort 

Prints a message 
execution. This 
nonfatal errors 
messages. . .". 



in the minibuffer and 
function is intended for 
such as "User not 



continues 
reporting 
accepting 



minibuf f er-print 

Prints a message in the minibuffer, but not during 
macro execution. This function is intended for use by 
extensions that print messages in the normal process of 
their execution, such as the line count from A X=. For 
this_ function, as well as the others below, in 
multiline minibuffer situations, an appropriate line is 
chosen based upon availability of empty lines and 
several other criteria. 

minibuf fer-print-noclear 

Prints ^ a message in the minibuffer (not during macro 
execution), but does not erase the previous contents. 
Output is appended to the last minibuffer line used. 

display-com-error 

Prints a message in the minibuffer and aborts to editor 
top level. Its first argument is a Multics standard 
error code. Its remaining arguments are character 
strings or symbols. See "Multics Error Table" below 
for the technique used to get error_table_ values into 
your program. 

display-com-error-noabort 

Prints _ a message in the minibuffer and continues 
execution. Its first argument is a Multics standard 
error code. 

minibuf fer-clear 

Clears out_ the last minibuffer line that was written, 
except during macro execution. This function should be 
used to clear out minibuffers written in by 
minibuffer-print and minibuf fer-print-noclear at the 
end of subsystem invocation. 
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display-error-remark 

Identical to display-error-noabort, except that the 

particular minibuffer line on which this remark is 

printed becomes the next one overwritten for any 

minibuffer remark or output. This function should be 
used for transient remarks (such as "Writing", 

"Modified", etc.), that you wish to remove from the 
screen as soon as possible. 

command-quit 

Aborts to top level (or to the minibuffer if, one is 
being entered) and rings the terminal bell. Execution 
of the current extension code is irretrievably stopped. 
This function is used by display-error and 
display-com-error internally; since it is better to 
print a message when an error occurs, generally use 
these latter two functions instead of command-quit. Do 
not use command-prompt-abort (what A G invokes) to error 
abort out of code, since it would abort minibuffers as 
well. 

ring-tty-bell 

Rings the terminal bell (or beeper) with no other 
effect. All. error aborts out of code, such as those 
caused by display-error and display-com-error, do this 
by default.. 

VARIABLES 

Many groups of Emacs requests need global variables to 
communicate among themselves and the functions they call. A 
global variable is a Lisp variable that is not the parameter of 
any particular function; its value can be accessed or set by any 
function. Some of the global variables in Emacs are highly 
user-visible, for example, "fill-column", which contains the 
column number of the fill column as set by A XF, and used by the 
filling requests and fill mode. Similarly, the character string 
that is the comment prefix is the binding of the global variable 
"comment-prefix". Extensions often need global variables to 
communicate among their parts. 

Normally, global variables in Lisp are accessed just like 
other variables, i.e., those that are parameters of functions or 
prog or let variables. For instance, a function to set the fill 
column to 30 if it is over 40, might contain the code: 

IXC I >* £ J 1 1 1 .._.. An \ / -. „ J.— C 1 1_«n1 , im*-> 1ft \ \ 
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When a global variable is used in your program, say one 
named "my-global", the "declaration" 

(declare (special my-global)) 

must_ appear in the program before its first use, to tell the 
compiler about this "special" variable (the Lisp term for a 
global variable). The e-macros include file declares many of the 
provided global variables, which you need not declare, 

defvar 

An even more powerful way to declare your own global 
variables is provided by the defvar declaration/special form. In 
its simplest form: 

(defvar my-global) 
is equivalent to: 

(declare (special my-global)) 
but is simpler and more mnemonic. 

Use defvar to specify an initial value to be assigned to the 
global variable at the time the program is loaded. This value 
will be assigned only if the variable has not already been 
assigned a value; this makes it ideal for user-settable options. 
For example; 

(defvar magic-mode-debug-f lag nil) 

not only declares magic-mode-debug flag special, but gives it a 
value of nil (remember that the binding of the variable nil is 
the symbol nil) if the user has not assigned a value to it before 
loading the magic-mode program, where this declaration presumably 
appears. 

PROVIDED GLOBAL VARIABLES 

You have already encountered some of the global variables in 
Emacs during the introduction to Lisp; for example, the global 
variables t and nil that contain the standard indicators of truth 
and falsity. There are also global variables whose values are 
symbols whose printnames (see "Character Dispatching") are 
hard-to-type characters. Most of the interesting global 
variables in Emacs are associated with given buffers, such as 
variables containing the pathname and comment column (this is 
discussed below). 
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There are, however, a few truly global variables that Emacs 
uses. Here are two of them you might need to use. You need not 
declare them special, since they are declared in the e-macros 
include file. 

env-dir 

a string that is the pathname of the directory 
containing all the Emacs library programs. 

process-dir 

a string: that is the pathname of your process 
directory- 

Per-Buf fer Variables 

The global variable situation is complicated by the fact 
that editing activity is usually local to each buffer. That is, 
if a set of global variables contains a set of values about what 
is being edited, it usually pertains to what, is going on in only 
one editor buffer. If you switch to a different buffer, and use 
the same editor facility, you do not want to use or change the 
values of those global variables that pertained to activity in 

variables unusable, because all functions would have to keep 
track of what buffer they are talking about before using any 
global variables, and therefore maintain several sets of them. 
Fortunately, it is a lot easier than that. The buffer-switcher 
in Emacs saves and restores values of global variables as buffers 
are switched, if you tell it what variables you want so saved and 
restored, when the buffer you are operating in is exited and 
reentered, respectively. Such a variable is called a per - buf fer 
variable , and the act of telling the buffer-switcher about it, 
thereby associating its current value with this buffer, is called 
registering it. Once a variable has been registered in a given 
buffer, the functions that use it can assume that its value will 
be what it last was in that buffer whenever the editor enters 
that buffer. Another term for a per-buffer variable is a local 
variable . The following two primitives exist for registering 
local variables; there are no primitives for setting or 
retrieving their values, because the whole point of this 
mechanism is to allow them to be accessed as normal Lisp 
variables. 

register-local- variable 

Called with one argument, the symbol whose name is the 
name of the local variable you wish to register. 
Registers it in the current buffer, if not already 
registered there, and the variable initially inherits 
its "global value". If registered, its value is left 
alone. If it has no global value, it acquires the 
symbol "nil" as its value if this is its first 
registration in this buffer. 
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establish-local-var 

Just like register-local-variable, but takes a second 
argument, a default value to be initially assigned to 
the variable the first time it is registered in this 
buffer, if it has no global value. 

The global value of a per-buffer variable is the value it 
has in buffers in which it is not registered. It is this value 
that is set if you set this variable while in a buffer in which 
it is not registered. A local variable "inherits" its global 
value when it is first registered in a given buffer. For 
variables that have no global value (i.e., were never assigned 
one), establish-local-var can be used to provide default 
initialization. 



EXAMPLE OF LOCAL VARIABLES 

Three functions that maintain a "problem count" in a given 
buffer are started up by typing ESC X monitor-problems CR. Once 
started, use A XP to count a problem, and A XR to report the number 
of problems noted: 

(defun monitor-problems () ; command-level function 

(set-key ' A XP * note-a-problem) ;set the keys needed, 
(set-key ' A XR 'report-problems) ;only in this buffer 
(establish-local-var 'problem-count 0)) ; register the 
; local var, initial value here. 

(defun note-a-problem () ;executed on A XP 

(setq problem-count (+ 1 problem-count))) ;Increment the 

; variable 



(defun report-problems () ;on A XR 

(minibuf fer-print "There have been " 

(decimal-rep problem-count) 
" problems in this buffer.")) 

By calling establish-local-var on the symbol 
"problem-count", the programmer here has ensured that the 
problem-counts in each buffer in which he counts problems will be 
maintained separately. 
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REGISTERED VARIABLES 

The following per-buffer variables are automatically 
registered by the editor. Their values can be inspected or set 
in extension code. 

buffer-modified- flag 

Contains t or nil, indicating that this buffer has or 
has not been modified since last read in or written. 
Set automatically by the editor. Modification of a 
buffer executed within the special form: 

\, w A l_UUUU~ iiiGu x a. jr 111^ ^j.wj.uii' ^i.wtui*.' ... -*.**». »«w*/ 

does not set this flag. 

read-only-flag 

Contains t or nil indicating whether or not this is 
read-only buffer. The editor does not set this flag; 
it is set only by extensions. An attempt to modify the 
text in this buffer produces an error and a quit to 
editor command level if this flag is on and 
buffer-modified-flag is off (nil). The buffer can be 
modified, however, by functions executed from within 
extension code within a "(without-modifying ...)". 

fpathname 

Contains the full Multics pathname associated with this 
buffer by the last file read or written into/out of it, 
or by find-file. It is nil if there is none. Changing 
it from extension code modifies or "forgets" the 
pathname as you set it. 

der-wahrer-mark 

Contains the mark associated with the user-visible mark 
that A X A X and other related requests see. Is nil if 
the user set no mark in this buffer. Do not set this 
variable; call set-the-mark to do so. 

current-buffer-mode 

Contains the major mode in effect in this buffer. The 
value is a symbol. To state that a major mode of your 
construction is in effect in a buffer, simply set this 
variable. 

comment-column 

Contains the comment column, measured from 0. 

comment— ^ref ix 

Contains the string, which can be a null string, that 
is the comment prefix. 
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tab-equivalent 

Contains the number of spaces for a tab. Initialized 
to 10., the Multics standard, this can be set either in 
code or by ESC ESC to edit code from other operating 
systems. The redisplay obeys this variable too, but 
not in two-window mode. 

buffer-minor-modes 

Contains the Lisp list of symbols representing the 
minor modes in effect in this buffer. 

MODE HOOKS 

Emacs provides a set of global variables called mode hooks . 
Most major modes currently have mode-hook variables. The 
mode-hook variable for a major mode allows a user to run his own 
code every time a certain major mode is entered. For instance, a 
user might want to set certain key bindings every time he uses 
PL/I mode. The mode-hook variable is generally named 
XXX-mode-hook for XXX mode. The following are currently defined: 

MODS NAME OF HOOK VARIABLE 

EMAIL rmail -mode -hook 

MAIL mail-mode-hook 

PL/ 1 pll-mode-hook 

FORTRAN fortran-mode-hook 

ALM aim-mode-hook 

LISP lisp-mode-hook 

LDEBUG Idebug-mode-hook 

TEXT text-mode-hook 

To use the mode hooks, write a function that is to be 
executed every time the mode is entered. (This function is 
usually defined in the Emacs start_up.) For example: 

(defun Mike-pll-mode-hook() 

(set-key "ESC-*" ' search-f or-journalization-notice) ) 

In the start_up, set the variable pll-mode-hook to the symbol 
Mike-pll-mode-hook. This is done with a statement of the form: 

(setq pll-mode-hook 'Mike-pll-mode-hook) 

Thus, every time Mike enters PL/I mode, the function 
Mike-pll-mode-hook is run, binding ESC + to Mike's 
journalization-notice finder. 

Modes use defvar to assign nil to their mode-hook variables 
if the user (via his start_up) has not assigned something else. 
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| Other User Hooks 

Several additional hooks for functions to be called at 
special times are available. In order to use them, write your 
own function, of one argument, and use setq to set the 
appropriate hook to the name of your function. The one argument 
passed is the name of the hook being invoked. These include: 

buffer-creation-hook 

called when a buffer is created.. 

buffer-destruction-hook- 
called when a buffer is destroyed. 

buffer— entrance— hook 

called when a new buffer is selected. 

buffer-ex it-hook 

called when a buffer is left. 

close-line-hook 

called when the user moves to another line. 



LARGE SCALE OUTPUT 

Output of multiline information, or information longer than 
about 60 characters, should not be done via minibuffer printing, 
but. via the local - display , or printout facility. This is the 
facility with which buffer listings, global searches, apropos, 
and other requests display their output. On video terminals, it 
displays lines at the top of the screen, asking for "MORE?" as 
each screen fills up. At the end of the local display, it waits 
for the user to type the next Emacs request, and then restores 
the screen. On printing terminals, the data is simply printed 
line by line, with no "MORE?" processing or pausing at the end. 
The local display facility is an integral part of the Emacs 
redisplay. 

Three functions used in generating local displays are: 

in it-local-displays 

Is called with no arguments to start a local display. 

It sets up the necessary redisplay mechanism, 

initializing it to the top of the screen. 

local-di splay-generator 

This function is called with a string, whose last 
character must be a newline, and displays it as the 
next line (or lines, if continuation lines are 
required) of local output. If you do not have a 
newline at the end of your string, calling 
local-display-generator-nnl instead provides one 
automatically. There must be no embedded newlines in 
strings for local output. A null string causes an 
empty line. 
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end- local-displays 

Finishes a local display, restoring the screen. Causes 
the next redisplay to be suppressed, so the local 
display remains visible on the screen. 

The sequence of calls: 

( init-local-displays) 

(local-display-generator{-nnl} ...) ;perhaps many 

; times 
( end-local-di splays ) 

correctly produces a local display. 

The best way to generate a well-formatted local display is to 
set up a temporary buffer (see "Manipulating Buffers" below), 
build some text in it, and display its content, in part or in 
whole, as a local display. Three functions are provided to 
facilitate this: 

local-display-current-line 

Does a local-display-generator on the current editor 
line in this buffer. 

display-buf fer-as-printout 

Does an init-local-displays, and displays all lines of 
the current buffer as local output. It does not do an 
end-local-displays,* you have to do that yourself, 
hopefully after you have gotten out of your temporary 
buffer and cleaned up whatever else you had to. 

view-region-as-lines 

Displays the entire point-to-user-visible-mark as local 
display, making all the necessary calls, including 
end-local-displays . 

While in a function that has a local display in progress, 
you must never call the redisplay (see "Calling the Redisplay" 
below), or call minibuf-response or any other function that 
causes redisplay, for that instantaneously restores the screen 
contents to the windows on display, obliterating the local 
display in progress. 
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The following function locally displays all lines in the 
buffer that contain the string "defun": 

(d'efun look-for-defuns( ) ;use ESC X look-f or-defuns CR 

(save-excursion ; remember where you are. 

(go-to-beginning-of -buffer) 

(init-local-displays) ;set up for printout, 
(do-forever ;loop the buffer 

(if (forward-search-in-line "defun") ;look for 

; "defun" 
(local-display-current-line)) ;cause printout 

;of it 
(if (lastlinep) (stop-doing) ) ;check for EOB. 
(next-line))) ;'Go to start of 

;next line 
(end-local-displays)) ;wait for user, and 

;next request 

A special form, display-as-printout , is available. It 
generates a new buffer, executes your contained forms, displays 
the whole buffer as local display, destroys the buffer, and 
returns. Its syntax is: 

(display-as-printout 
<FORMl> 
<F0RM2> 



<FORMn> ) 

MANIPULATING BUFFERS 

Often, the easiest way to do string processing in the editor 
environment, i.e., handle strings, catenating, searching, etc., 
is to use the primitives of the editor itself, since it is a 
string-processing language. To do this, temporary buffers are 
necessary. To create a buffer, you should use the primitive 
go-to-or-create-buf fer (what A XB uses), which goes to a buffer 
associated with the symbol you give it as an argument. 

Most symbols are kept in a registry: this registry is 
called the obarray , and there is only one symbol of any given 
name in it. A symbol registered in the obarray is said to be 
interned . Only one interned symbol named "joe" exists, but you 
can create many uninterned symbols named "joe". If you refer to 

a sumhnl namod " -ina" in a nrnnram hftua«sr hw cawinn " ' ina" unn 

always get the interned one. 
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A major feature of symbols in Lisp is that they can be given 
properties , arbitrary user-defined attributes. These attributes 
are catalogued "in" the symbol via indicators , symbols that 
indicate what property you want. The Lisp functions "putprop" 
and "get" store and retrieve properties. 

(putprop 'Fred 'blue 'eyes) ;Gives the interned symbol 

;named "Fred" an "eyes" 
;property of "blue". 

(get 'Fred 'eyes) ; retrieves the property under the 

; indicator "eyes", and thus returns 
;the interned symbol "blue". 

In Emacs, symbols represent buffers. All of the information 
associated with a buffer, is catalogued as properties of some 
symbol whose name is the name of the buffer. Thus, it is 
possible to have two buffers of the same name, which would imply 
that of the symbols representing them, only one is interned. The 
A XB request always uses the interned symbol of the name given; 
that is why you can A XB back to an existing buffer instead of 
creating a new one each time. 

Creating a Temporary Buffer 

To create a temporary buffer, you must first create an 
uninterned symbol, to make sure that you are not going to switch 
to a buffer that is already real. To'do this, you give a string 
to be used in naming the symbol to the Lisp cliche: 

(maknam (explodec "A string")) 

The explodec blows the string apart into a Lisp list of 
characters; the maknam builds a symbol out of it. The value of 
this form is the new symbol. You can then go to a (guaranteed) 
new buffer of that name, i.e., 

(go-to-or-create-buf fer (maknam (explodec "A string"))) 

and the global variable "current-buffer" will have that symbol as 
its value. A temporary buffer is one that is destroyed 
automatically by the editor upon switching out of it. To make a 
buffer temporary, all you have to do is give the symbol that 
represents it (the "buffer symbol") a "temporary-buffer" property 
of the symbol "t". This can be done by the Lisp form: 

(putprop current-buffer t 'temporary-buffer) 
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(The variable "t"' is always bound to the symbol "t"). Once this 
has been done, you must be careful not to switch out of this 
buffer until you are done with it. If your code involves 
manipulating many buffers, some of them temporary, you must give 
the temporary buffers their temporary-buffer properties at the 
end of your manipulations. 

A better way to do this is via the set-buffer-self-destruct 
function.. Calling; this function upon the buffer-symbol, as 
be-lowr 

( set-buif er-self-destruct current-buffer) 

schedules the buffer for deletion as soon as the buffer is 
exited. Using this, you find out sooner if you mistype this 
function name than if you mistype the temporary buffer property. 

When a new buffer is created, i€ contains one line, which 
consists of a linefeed only.. There are no truly empty buffers in 
Emacs. The predicate empty-buff er-p can be applied to a buffer 
symbol to determine if that buffer is in this state. When 
buffers are switched, all information related to the old buffer 
is stored as properties of the buffer symbol: this includes not 
only the local variables registered in that buffer, but the 
location of point, the user-visible (and all other) marks, etc. 
Thus, when buffers are switched back and forth, the cursor 
retains its position in each buffer (as can be seen while 
editing), although the redisplay might choose to display a screen 
differently after visiting another buffer and coming back. 

Some applications require making a nontemporary buffer, 

putting some text in it, and going back there on occasion. 

Therefore, you might want to go into a nontemporary buffer of an 
interned buffer symbol: 

(go-to-or-create-buf fer ' name-and-address-buf fer) 

or perhaps keep a global ( not per-buffer) variable that you set 
once to an uninterned symbol: 

( setq name-and-address-keep-track 

(maknam (explodec "Name and Address Buffer"))) 

and switch into it by saying: 

\yu i.u vi. utccii-c uuiici. name auu auuicss rwegj-f tiaCX j 
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The function buffer-kill can be called with a buffer symbol 

to destroy a buffer. The function destroy-buf f er-contents (of no 

arguments) can be called to reduce the current buffer to a single 

"empty" line (buffer contents are not pushed onto the kill ring). 

don t ~ not ice - modi f ied - buf f er 

When you create features and modes that interact with the 
user either by placing "results" in a buffer, accepting user 
input typed "into" a buffer, or both, these buffers will be 
"noticed" _ when the user leaves Emacs, with the standard query 
about modified buffers. However, you can prevent quit-the-editor 
(what A X A C invokes) from taking notice of a given buffer even 
though that buffer is modified. This is done by marking the 
buffer concerned with the dont-notice-modif ied-buf fer function. 
It takes a single argument, which is the buffer symbol of the 
buffer concerned. 

Variable for Buffer Manipulation 

The following two variables are relevant to buffer 
manipulation: 

current-buffer 

The value of this variable is the buffer symbol of the 
current buffer. Do not change it, or incorrect 
operation results. Use go-to-or-create-buff er. 

previous-buffer 

The value of this variable is the buffer symbol of the 
last buffer, which is returned to when A XB CR is typed. 
It is acceptable to setq this variable. 

The go-to-or-create-buf fer function accepts a buffer-name of 
""as meaning go to that previous buffer. 

The save-excurs ion-buffer Special Form 

The special form save-excursion-buf fer is invaluable when 
«-*«.-...•) iuutatiwiib uiwi. aniLku uuiisrs. it provides for 
remembering which buffer you were in, and switching back to it 
when you are done. It also saves and restores the state of 
"previous-buffer". The save-excursion-buf fer is like 
save-excursion; it executes its contained forms while pushing the 
buffer-state of the editor on an internal stack, and returns the 
value of the last form within it. 
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The following program, when invoked after typing somebody's 
name (say you hook it up to a key), follows it with his title in 
parentheses. Assume the file >udd>FamNam>personnel_data looks 
like this: 

Washington, G. =Lumberjack 
Duck, D. =Pe.ssimi.st 
Nietzsche, F. =Exi stent ialist 
Mouse, M. =Optimist 
Eisenhower, D, D.. =Golfe.r 

(def mt insert-persQti-title ( ) 

( 1 <»+■ I .( na-ma t eaira-o.vmirei r\rt •p^no <im.' <■» — .— ■; ^ x. 



get to end of word 
m - end of word 
go to beg. of wd„ 



( skip-back-whi t espace ) 

(with-mark m 

(back ward- word) , „ _ _ . --„. _ 
(catenate ( point-mar k-to-string m) 

","))))) 

; return the word with a " , " after it. 
(insert-string ; insert 

(catenate * (" ;.open par en and sp 

(save-excursion-buf fer ;save the old buff 
(go-to-or-create-buf fer ' name-position-records) 

;go to stuff 
(if ( empty-buff er-p current-buffer) ;read it 

;once 
(read-in-f ile B >udd>FamNam>personnel_data l, ) ) 



(go-to-beginning-of-buf fer) 
(do-forever 
(if (loo king- at name) 



set up for search 

scan lines 

Is point at 

"name,"? 

look for the =. 

get to the end. 



(forward-search "=") 
(return (with-mark n 

(go-to-end-of-line) 
(point-mark-to-string n)))) 
(if (lastlinep) (return "???"}) ^couldn't 

;find him 
(next-line)) ?move on 

") "))))) 
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This function picks out the name you just typed by skipping 
back over whitespace, and picking up all between there and the 
start of the previous (current) word. it then inserts, between 
parentheses, the portion of that line of the data file that 
contains the sought name at its front after the equals sign. The 
buffer name-position-records is read into once, and contains the 
data file thereafter. 

The initial save-excursion remembers the user's point 
location while the word is collected. The save-excursion-buffer 
remembers what buffer and where in it all its modes, local 
variables, etc., are, while you operate in the data file buffer. 

The function catenate is a valuable one in the context of 
Emacs; it takes any number of strings (or symbols, whose 
printname will be used), builds a string by catenating them 
first-to-last, and returns it. ' 

Another useful function in this context is apply-catenate , 
which takes as an argument a list of any number of strings or 
symbols and builds a string by catenating the strings and names 
of the symbols, first to last. 

CALLING THE REDI SPLAY 

The Emacs redisplay decides what lines of the current buffer 
should be shown on the screen, determines how to modify the 
current screen to show the contents of those lines, and updates 
the screen in an optimal manner. It is called by the editor 
whenever there is no more input available. It is very simple to 
call. It takes no arguments, i.e., you just say: 

(redisplay) 

The redisplay does not know or care by what means the buffer 
wasmodif ied; if you delete several words with ESC D, A D, or A W, 
it is all the same to the redisplay, and it acts similarly in 
updating the screen. Normally, the extension writer need not be 
concerned at all about the redisplay. A major feature of Emacs 
is that only the total effect of a complex manipulation is 
displayed, not every small operation that the manipulation used 
to achieve its effect. 
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In some situations, however , it is. advantageous to call the 
redisplay explicitly from extension code. One example is a 
function that takes a. tremendous amount of computer time and 
might wish to update the screen every, so often as it finishes 
some major section. You do not tell the redisplay what to 
display or how to. display it; it displays some excerpt of. the 
current buffer that contains the current line, and shows the 
cursor where the current point is. If you call it during a 
buffer excursion, i.e.., while in some special buffer in a 
function, it displays that buffer, around its "point". As soon as 
that function returns to editor command level, the screen is 
overwritten with, the original buffer's lines* Thus, calling 

L eVAASy.LCLjr i» UVL LU WCB UVUaiUClCU Ct- &UUai.l LULC I.UI 1UV.C11 

displays* 

The most common need for calling redisplay is in functions 
that add text (or change text) on a line, and move to another 
line. For example, the electric semicolon of electric PL/I mode 
adds a semicolon to the current line and moves, to the next. On a 
printing terminal, the user would never see the semicolon unless 
special action, were taken.. The text in the buffer would indeed 
be right, but by the time the next redisplay occurred (the 
electric semicolon request returned),, the, editor would be off 
that line, and thus would display the next line, where the 
electric semicolon request left it. While this is correct, the 
printing terminal user looking at his type-in would, with, some 
validity, complain that "all the semicolons seem to be missing". 
Thus, the electric PE/I semicolon request calls the redisplay 
immediately after it executes "(insert-string ";")". 

The following is a function for a "card-numbering FORTRAN 
mode", which when invoked (perhaps hook it up to CR) puts a 
sequence number in column 72 (71 from 0) and goes to column 7 of 
the next line. It must call the redisplay so that, on a printing 
terminal, the card numbers get shown: 

(defun fortran-next-line () 

(whitespace-to-hpos 71.) ;go to col 72. 

(insert-string (decimal-rep cardno)) ;cardno is a local 

;buffer var 
(setq cardno (+ 1 cardno)) ;up the next 

;card number 
(redisplay) ;let printing 

; user see. 
(new- line) ;get to 

;next line 
(whitespace-to-hpos 6.)) ;6 rel = card col 7. 
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Another commonly called redisplay function is 
full-redisplay , of no arguments, which clears and rewrites the 
screen, as with A L with no arguments. 

Positioning Text on the Screen 

Emacs usually positions text on the screen automatically. 
When the cursor is moved to text already on the screen, it is 
simply repositioned on the current screen. If the text is not 
already on the_ screen, Emacs usually centers the line containing 
the # text positioned to in the current window. Sometimes, it is 
desirable to have other than this default action. You may wish, 
say, to position some text onto the top of the screen from 
extension code; this is what ESC 1 A L does. The 
redisplay-current-window-relative function is what 
redi splay-command ( A L) calls when given an argument. Thus, 

(redisplay-current-window-relative 3) 

redisplays the current window with the current line of the 
current buffer on line 3 of the window. 

EIS TABLES 

The Emacs environment provides a facility for utilizing the 
sophisticated Multics processor instructions for scanning for 
characters in, or not in, a particular set of characters. These 
operations correspond to the PL/i "search" and "verify" builtins. 
The word requests' operate using' these facilities." 



A set of characters is represented by a charscan table , a 
compound Lisp object occupying about 200 words of storage. You 
can get a charscan table by giving a set of characters, as a 
string, to the function charscan-table. It returns a charscan 
table representing that set of characters: 

(setq number-verify-table (charscan-table "0123456789+-")) 

Functions Using the Charscan Table 

Given such a table, there are a set of functions that can be 
called to utilize it to search for characters in or out of that 
set, backward, forward, whole buffer, or only one line. All but 
the last of the following functions take one argument, a charscan 
table representing a set of characters (called S here). They 
return nil (falsity) if they hit the end of the buffer or line 
(as appropriate) without finding what they are looking for. If 
they succeed, they move point and return a truth indication. If 
they fail, they do not move point. 
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search- for- f irst-charset-line 

Scans current line forward from point. Success is 
stopping to the left of a character in S. 

search-f or- first-no t-char set-line 

Same as above, but success is stopping to the left of a 
character not in S. 

search-back- f irst-charset-line 

Scans current line backward from point. Success is 
stopping to the right of a character in S. 

search—back— first— not.— char set— line 

Same- as search-back-f irst-charset-line, but success is 
stopping to the right of a character not in S. 

search-char set-forward 

Scans the buffer from point to the end of the buffer. 
Success is stopping to the left of a character in S. 

search-char set-backward 

Scans the buffer backward from point to the beginning 
of the buffer. Success is stopping to the right of a 
character in S. 

search-not-char set- forward 

Scans the buffer forward from point to the end. 
Success is stopping to the left of a character not in 
S. 

search-not-charset-backward 

Scans the buffer backward from point to the beginning 
of the buffer. Success is stopping to the right of a 
character not in S. 

char set-member 

A predicate; takes two arguments: a character and a 

charscan table. The character can be a single 
character string, a single-character-named symbol, or a 

numeric ASCII value. Returns true if the character is 

a member of the set of characters represented by the 
charscan table. 



The following function finds the first nonnumeric character 
on the line it is invoked on: 

(defun find-first-non-numeric () 

(establish-local-var numscan-table nil) ;does 

;var exist 
(if (not numscan-table) ;if nil, i.e., not init yet, 

(setq numscan-table (charscan-table "0123456789"))) 
(go-to-beginning-of-line) 
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(if (not (search-for-f irst-not-charset-line 

numscan-table) ) 
(minibuffer-print "Line is O.K.!"))) ;failure 

;is all are 

?in charset 

OPTIONS 

( The Emacs option mechanism provides for user-settable 
♦variables in the Lisp environment. The only difference between 
an option and any other global Lisp variable in the editor 
(basic or extended) is that the options are listed at the 
user-visible level by typing ESC X opt list CR, and can be set or 
interrogated via the opt request. The option mechanism also 
provides for checking that numeric variables stay numeric, and 
that variables restricted to "t" or "nil" as values stay 
restricted to those values. * 

> Thus, options can control per-buffer or truly global 
variables; the option mechanism imposes no restraints upon the 
dynamic scope of the variables managed by it. The option 
mechanism also provides for a default global value of variables 
it manages. 

A global variable is registered with the option mechanism by 
invoking the function register-option upon the Lisp symbol that 
represents (has the name of) that variable, and its default 

rlZZZ7~lZ~ZV " wVI" VOiU f AS a numoer, cne option mechanism 
restricts the variable's value to numbers; if it is one of t or 
nil, the option mechanism restricts its values to t or nil (which 
you indicate as "on" or "off"). 

The choice of whether a variable should be made an official 
option or not depends upon whether or not you want the user to 
see it when an opt list" is done, and whether finer control than 
tnat provided by the option mechanism over the values assigned to 
f? re ;V ecessary ' „ ** is acceptable to register an option the 
first time some code is executed; only then does it appear in the 
option list. It is usual to have forms invoking register-option 
at "top-level" m a file full of code. i.e. ou?«^e o* a«" 
function. Such code is executed when the code' is brought*into 
the editor environment. 

The following code registers an option describing default 
paragraph indentation, and shows a function that creates a new 
paragraph (that should probably be hooked up to a key). Like all 
Lisp global variables, options must be declared "special" for the 
Lisp compiler (see "Compilation" below): 
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(declare (special paragraph-indentation)) ;for compiler. 

(register-option 'paragraph-indentation 10.) ; default is ten 

(defun new-paragraph ( ) 

(new-line) ;two new-lines 

(new-line) 

(whitespace-to-hpos paragraph-indentation)) ;tab out 

By issuing the request: 

ESC X opt paragraph-indentation 5 CR 

You can set the amount of indentation inserted by new-paragraph 
to 5. 

NAME SCOPE ISSUES 

All of the functions and variables in the Lisp environment 
are accessible to all functions running in it. At times, this 
can be a problem. When adding your own extensions to the editor 

_ _...£*•.».■»_..•■..•.*. •«.•*.*» 1* ~ •* «■• «m«*m.*^m4>#* *trt*i £ *.*^rr. ^KrtAei nn » r> 9 m a f at" Ana r\T 

ei|viiunuicnL r nuuiixny ^tcvSuuo jrwu num s.uv«si»i>j u >4uu><_ *.w*. ■>*..». •*■ - 

your functions that happens to be the name of some internal (or 
user-visible) function in Emacs. Occasionally, there may be 
reason to do this deliberately, e.g., writing your own version of 
next-line to do something special. This is dangerous, and not 
recommended. 

In general, you want to make sure that none of your 
functions or variables conflict with those of the editor. The 
best way to do this is to choose some set of names that minimizes 
the possiblity of conflict. To achieve this, use capital letters 
anywhere (such as initial capitals) or use underscores^ in your 
names, since almost no Emacs or Lisp system functions have 
leading capitals or trailing underscores. Watch out for the few 
exceptions: error_table_, e_cline_, Rtyo, Rprinc, ItoC, Ctol , 
and the DCTL functions for writing terminal control modules. 
There are a few Lisp system functions with embedded underscores, 
but other than make_atom, it does not hurt if you accidentally 
redefine them. The Lisp compiler also warns you if you attempt 
to redefine a system function. No functions in Emacs contain 
underscores in their names. 

Another technique is to use double hyphens in your names. 
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Another way to avoid name scope conflicts is to prefix all 
of your names in a given package with some prefix indicative of 
the facility that you are trying to implement. For instance, if 
you are implementing a SNOBOL edit mode, you might name your 
functions "snobol-f ind-match-string" , "snobol-get-branch-target" , 
etc. The same holds true for global variable names. This is the 
standard, recommended, and most mnemonic way. 

You can also be reasonably certain that names constructed 
somewhat whimsically (e.g. , "Johns-special-tsplp-hack", 
"find-third-foo", etc.) will not conflict. 

MODES 

The major and minor mode mechanism of Emacs is a way for the 
user to switch in and out of large sets of key-bindings and 
column settings, and to be informed of this via the mode line. 

Major Modes 

A major mode involves a large body of optional code (e.g., 
PL/I mode), sets up for editing code written in a particular 
language, or sets up buffer for some highly specialized task 
where very common keys (e.g., CR) do nonobvious things (e.g., the 
Message mode buffers of the Emacs message facility). Minor modes 
generally involve the way that whitespace or delimiters are 
interpreted, e.g., fill mode and speedtype mode. 

Although modes can be invoked by explicit user commands, 
e.g., ESC X lisp-mode, modes are usually invoked via find-file 
( A X A F) when a user reads in or creates a program and has elected 
the find-file-set-modes option in his start_up. When you invoke 
find-file with a suffixed file (and with find-file-set-modes 
elected), a check is made to see if a function named XXX-mode 
(where XXX is the suffix) has been defined. If such a function 
has been defined, it is invoked. If not, a check is made to see 
if the symbol XXX has a suffix-mode property; if so, the value of 
this property is a symbol denoting a function to be invoked. 
Thus, a form such as: 

(putprop 'ec ' exec-com-mode 'suffix-mode) 

in a start_up causes all ".ec" segments to invoke the 
(hypothetical) function exec-com-mode. The defprop special form 
can be used to eliminate the quotes; thus, 

(defprop ec exec-com-mode suffix-mode) 

has the same effect as the form above. 
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A major mode is set up by a user-visible function called 
"XXX-mode", where XXX is the name of the mode. This "mode 
function" establishes key-bindings (using set-key), and sets 
columns {e.g., fill-column, comment-column) and prefixes as 
necessary. The mode function establishes the mode by setting the 
per-buf f er-variable "current-buffer-mode" to a symbol whose name 
indicates the mode. The name of the symbol appears in the mode 
line when the redisplay is invoked while in this buffer. The 
following function sets up a major mode for editing FORTRAN 
programs : 

(defun fortran-mode () ;the mode function 

(setq current-buffer-mode 'FORTRAN) ; symbol 

;for mode 
(setq fill-column 70.) yset columns 

(setq fill-prefix" ") ;six spaces on CR 

(set-key 'CR 'fortran-new-line) ?set up CR key 
(setq comment-column 0) 

(setq comment-prefix "C ") ?that begins cmts 

( if f ortran-mode-hook 

( f uncall f ortran-mode-hook ) ) ) 

The function fortran-new-line is assumed to be one that does 

eompfhi no annrnnriaf-o cnr^'h ac nnmhorinn f^r-Ae TV>«» nea />f t-^o 

function set-key implies that this key binding (of the carriage 
return key) is local to this buffer, and will be reverted when 
this buffer is exited. 



The above code checks the variable f ortran-mode-hook to see 
if it is other than nil and invokes the symbol to which it is 
bound if it is indeed not nil. 

The Lisp primitive funcall is used to call functions that 
are the bindings of variables. It is like calling an entry 
variable in PL/I . The funcall function accepts any number of 
arguments; its first argument is the function you wish to call, 
and its second-through-last (optional) arguments are the 
arguments that are to be supplied to the function being called. 
Consider the statement: 

(setq Z (funcall X 1 2 4)) 

Suppose X is bound to the symbol +. The effect of evaluating the 
above statement would be to apply + to 1, 2, and 4, thereby 
assigning a value of 7 to Z. However, were X bound to * 
(multiply), a value of 1*2*4 (i.e., 8) would be assigned to Z. 
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The above code in fort ran -mode assumes that 
fortran-mode-hook will be bound to nil if it has not been set by 
the user. Of course, defvar elegantly provides for this. A 
statement such as: 

(defvar fortran-mode-hook nil) 

should appear somewhere in the source of f ortran-mode. 

Calling the mode-hook- function should be the last thing done 
by the mode function. 

Minor Modes 

Minor modes are less straightforward. Minor modes such as 
speedtype and fill mode have different actions associated with 
the keys they affect (for instance, all the punctuation keys), 
and the minor modes have to have detailed and specialized 
interaction between themselves. There is no way to generalize 
the interactions between the minor modes; no completely adequate 
solution to this problem has been developed. 

Minor modes are asserted and turned off in a given buffer by 
calling the functions "assert-minor-mode" and "negate-minor-mode" 
while in that buffer, with an interned symbol that identifies the 
mode (and appears in the mode line). A per-buffer variable 
called buffer-minor-modes has as a value a Lisp list of all the 
symbols identifying the minor modes in effect in this buffer. 
The Lisp predicate memq can be used to test whether a given 
interned symbol is a member of a list, and thus, whether a given 
minor mode is in effect in the current buffer: 

(memq 'fill buffer-minor-modes) 

returns a truth indication if fill mode is in effect in this 
buffer; otherwise, it returns "nil" (false). Functions 
implementing the actions of keys in minor modes should check in 
this way to see what other minor modes are in effect, and what 
they ought do in that case. 

The global variable fill-mode-delimiters is bound to a Lisp 
list of keys that act as punctuation in many minor modes. By use 
of the Lisp function mapc , all punctuation can be set to trigger 
a given action. The mapc function takes two arguments, a 
function and a Lisp list; the function is called upon each 
element of the list: 
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(defun no-punc-mode-word-on-a-line-mode-on () ;mode function 
(mapc 'word-on-a-line-setter fill-mode-delimiters) ;set 

;keys 
(assert-minor- mode ' word-on-a-line) ) ;get in mode line 

(defun word-on-a-line-setter (key) ;key is the key 

(set-key key ' word-on-a-line-responder ) ) ;set these keys 

(defun word-on-a-line-responder () ;key function 

(delete-white-sides) ;get rid of whitespace 
(self-insert) ; insert the typed character 
(new-line)) ;: start, a new line. 

This set of functions establishes a minor mode in which each word 
goes on a separate line as it is typed. 

CHARACTER DISPATCHING 

Several special forms and functions facilitate the making of 
decisions based upon the identity of. the character to the right 
(or left) of the current point. All of these functions and forms 
accept either of two ways of describing characters: either a 
single-character string (e.g., "."), or a symbol whose name_is 
that character (e.g., F a, as it would appear in a program), The 
first kind, is called the "string form", and the second kind, 
"character objects". 

The function curchar, of no arguments, returns the character 
to the right of the current point as a character object (this is 
done for storage efficiency; character objects are unique, while 
strings require allocation). You can test for two character 
objects being the same unique object (or any two objects, in 
general) via the Lisp predicate eq: 

(if (eq (curchar) 'a) 

(display-error "You are looking at an ""a"".")) 

You could do this with the looking-at predicate described 
earlier, but for single characters, looking-at is a lot less 
efficient, in both time and storage. 

You cannot use eq to test if two strings have the same 
characters in them; Lisp strings are not uniquely defined in the 
same way that symbols are uniquely defined via the obarray. Use 
samepnamep instead. 
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In order to facilitate the use of special characters (tabs, 

linefeeds, spaces, quotes, etc.) in this way, several global 

variables have values of the character objects for these 

characters: 

ESC ASCII ESC, Ascii 033. 

CRET ASCII carriage return (Ascii 015) 

NL ASCII newline (linefeed), Ascii 012. 

SPACE ASCII blank, Ascii 040. 

TAB ASCII tab, Ascii 011. 

BACKSPACE ASCII backspace, Ascii 010. 

DOUBLEQUOTE ", Ascii 042. 

SLASH /, Ascii 057, hard to type in Lisp code. 

A (eq (curchar) NL) is equivalent to (eolp). 

A special form to test if the current (to the right of 
point) character is a given character is called if-at: 

(if-at "&" (display-error "You can't have an ampersand here!")) 

Its syntax is the same as _if, i.e., it has one, none, or many 
"then" and/or "else" clauses, separated by the keyword "else" if 
there are any else clauses. However, instead of a predicate, 
if-at takes either a single-character string or a character 
object to be compared to the current character. If the current 
character is that character, the then forms are evaluated, etc. 
The if-at converts the character string to a character object at 
Lisp compile time, if necessary. The specification of the 
character must be a form that evaluates to the character of 
interest (e.g., "a", 'a, variable-bound-to-an-a) : 

(if-at TAB (delete-char) 

(whitespace-to-hpos next-field)) ;tab to next field. 

The exact effect (and actual implementation) of if-at is as 
though it were shorthand for: 

(if (eq (curchar) ) ) 

Similarly, a function called lefthand-char is like curchar 
except that it returns the character to the left of the current 
point; if the current point is at the beginning of the buffer, it 
returns a character object for a newline (which is almost always 
what you want). Similarly, an if-back-at special form exists, 
whose syntax and semantics are identical to if-at, except that it 
deals with the character to the left of the current point. 
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Two special forms for dispatching on the current (lefthand 
or righthand) character are called dispatch-on-current-char and 
dispatch-on-lefthand-char they dispatch upon the character to the 
right and the left of the current point, respectively: 

(declare (special parentable)) jglobal variable 
(setq parentable nil) ;done when code is 

; loaded into editor 

(defun count-parens-in-buffer () 

{if (not. parentable) ;i.f not initialised 

(setq parentable (char scan-table "()"))) ;init it 

( T ^.4*- ( I 1 a^V<^/Mi«4» A" \ / r*-^ f*\* ^«/mi«^- A \ \ • i ** i 4» 4*. W & r* *-* * 1 *■» Jk «?» 

\ -*•& <-, \ \ X^.^U.V*WUil W \J J \ **■ 4VJUWWVUI1 I*. \J J J , 4 1Ut UUC V VUiJ UiJ 

(save-excursion ;be nice 

(go-to-beginning-of -buffer) 
(do-forever 
(if (not (search-charset-forward parentable)) 

;look for ( or ) 
(stop-doing)) ;exit the do 
(dispatch-on-current-char ;see which 
( «(" (setq leftcount (+■ 1 leftcount))) 
( ")" (setq rightcount (+ 1 rightcount ) ) ) ) ) ) 
(minibuf fer-print (decimal-rep leftcount) " opens, " 

(decimal-rep rightcount) 
"closes.") ) ) 

The general syntax of dispatch-on-current-char and 
dispatch-on-lefthand-char is as follows: 

, (dispatch-on-current-char 

(CHI . <CHl-forml> 

<CHl-form2> 



<CHl-formn>) 
(CH2 <CH2-forml> 

<CH2-form2> 

<CH2-formn2>) 

(CHk * * <CHk-formi> 

<CHk-form2> 



<CHk-formnk>) 
(else <else-forml> 

<else-f orm2> 

<else-f ormn>) ) 
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CHi can be any form that evaluates to a single-character 
string or to a character object. When the current character 
(left or right as appropriate) matches a CHi, all of the 
<CHi-form> in that clause are evaluated sequentially, and the 
value of the last returned as the value of the 
dispatch-on-current-char (nil is returned if there are no 
<CHi-form>). If no CHi matches, the else clause is evaluated as 
though it were a matching clause. The else clause is optional; 
if omitted, and no CHi matches, nil is returned. 

READING CHARACTERS FROM THE TERMINAL 

Some Emacs subsystems, such as query-replace, "read" 
characters from the terminal, without echoing them, and base 
their course of action upon the character read. This is not the 
usual method of causing characters to produce effects; the 
key-binding mechanism (i.e., set-key) is the usual way of causing 
requests to be invoked by the typing of characters. However, the 
extension writer may encounter a situation where he expects a 
single character response to some question, and this facility is 
provided. Use this facility carefully: the correct way to 
implement functions like the directory and buffer editors is via 
modes and key bindings, not loops that read characters from the 
keyboard. Similarly, the minibuffer query functions (e.g., 
minibuf -response and yesp) should be used to ask questions. 

The get-char function is provided to read the next input 
character; get-char returns the numeric value of the ASCII 
representation of the character. Bear in mind that the next 
input character may well have already been typed, since input to 
Emacs is treated as a stream of typed characters. Therefore, 
get-char does not return to its caller until a character is 
available. The get-char function also performs the necessary 
services of maintaining the input traces displayed by help-on-tap 
( A _L), of handling keyboard macros, and of sampling for Emacs 
interrupts, such as those used by the Emacs console message 
system. 

The following Lisp functions, of one argument each, are 
provided to convert between numbers representing ASCII values of 
characters, single-character strings, and "character objects" 
(single-character symbols): 

Function Input Output 

ascii number single-character object 

ItoC number single-character string 

Ctol single-character number 

string or character 

object 
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Occasionally, programs that read characters from the 
terminal are designed to allow normal Emacs requests to be 
processed during these operations. This usually takes the form 
of either an "escape character," which means that the next 
character (s) are to be interpreted as a normal Emacs request, or, 
alternatively, the interpretation, of all characters "not known" 
to the. program as Emacs requests (the former method is preferred 
since it is much cleaner) . 

The process-char function receives as an argument a number 
representing the ASCII value of a single character to be 
interpceteu as the first: character of an Emacs request , anu so 
interprets and executes it (including reading of another 
character if necessary) according to the key bindings in the 
current buffer. 



In principle, the basic loop of Emacs can be expressed as: 

(do-forever 

(process-char (get-char)) 
(redisplay)) 

This is oversimplified; issues involving keyboard macros add some 
complexity, and the calling of redisplay is suppressed if input 
characters are available. Otherwise, the above code fragment is 
a correct description of the basic action of Emacs. 

PROGRAM DEVELOPMENT 

The editor itself provides many powerful tools for 
developing extension code and testing it while editing it. The 
following is a typical scenario in the development of an 
extension. 



You decide to write an extension. You sit down and think 
about it, and decide to code it. You enter Emacs. You do a A X A F 
on the shaver. lisp file to go into a new buffer with a proper 
file name and select Lisp major mode (assuming that you have the 
option for find-file-set-modes "on"). Then type the form: 

(%include e-macros) 

at the top of your file; this is necessary to compile it (see 
"Compilation" below), or to use the ESC X loadfile request, 
described below. The file e — macros, incl.lis 7 " 1 should be in the 
"translator" search rules for your process. For efficiency, put 
a link to it in the directory in which you do Emacs extension 
development. Now begin to type in a function: 
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(%include e-macros) 

{defun shave-line () 

(go-to-beginning-of-line) 

At this point, to type the next line, lining it up with the last 
Lisp form, use the indent-to-lisp request, which is on ESC CR in 
Lisp mode, and the next form automatically indents properly: 

(delete-white-space) ; wrong name given deliberately here 

When typing in Lisp in general, ESC CR (in Lisp mode) indents you 
on the next line the right amount. So, continue with: 

(go-to-end-of-line) 
(delete-white-space) 

Now you are looking at the buffer with the code for 

shave-line". To try it, load the code in the buffer into the 

editor. ESC A Z in Lisp mode does this. Immediately, you get the 
message: 

Unbalanced parentheses. 

This means that there were not enough close parentheses 
somewhere: Emacs could not find the boundaries of the Lisp form 
Fix the program problem. You are on the last line, so just tyoe 
the close parenthesis: 

(delete-white-space)) 

Now do the ESC A Z again. The cursor returns to the function you 
are trying to edit. To see if it works, invoke it from Lisp: 

ESC ESC shave-line CR 

ESC ESC puts parentheses around what you type, evaluates it, and 
types out the Lisp value so returned. However, you find the 
message: 

lisp: undefined function: delete-white-space 

printed in the minibuffer, with the terminal bell rung, so you 
must have the wrong function name. Since you know it is on a 
key, type: 

ESC X apropos white CR 
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and learn about delete-white-sides. Now go to the first line 
that has the bad function name, do an @ to clear the line, ESC A I 
to line up to retype the form, and: 

(delete-white-sides) 
Fix the other bad line, too, and again type: 

ESC ESC shave-line CR 
Surprisingly, it still says: 

lisp: undefined function: deiete-white-space 

as though you had not changed anything. Indeed, fixing it in _ the 
buffer is not good enough. You must reload it into the editor 
environment; use ESC A Z again. Now try it again: 

ESC ESC shave-line CR 

and immediately your function on the screen changes appearance; 
all the whitespace on the ends of the last line of the function 
disappears. It works, but its appearance is messy. This is a 
problem with editing what you are testing: it must either be 
innocuous, i.e., do'something harmless, or you must be prepared 
to reconstruct damage your function does, or switch to a test 
buffer before running it. 

Fix your function, and you are almost done. Although it 
exists in an editor buffer, and in the editor Lisp environment, 
you must remember to write it out: 

A X A S 

writes it out to shaver. lisp as you set up for initially. Now 

you have an operative Lisp program that you can use again. If, 

in a future invocation of the editor, you need to use it, you 
type: 

ESC X loadfile <path>shaver .lisp CR 

and get it into the environment. There are two problems with 
this, however: 

1. Whoever loadfiles must have e-macros. incl. lisp in his 
translator search rules. 

2. The code is executed interpret ively by_ the Lisp 
interpreter in the Lisp subsystem; Emacs is compiled 
Lisp,*" and compiled Lisp runs up to 100 times faster 
than interpreted Lisp and has fewer problems. 
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Thus, the file shaver. lisp should be compiled. Then, the 
compiled object segment can be loaded into the editor with: 

ESC X loadfile <path>shaver 
See below for a description of how to compile Lisp programs. 

Coding Problems 

Some other problems are of immediate interest to the 
extension writer. It is possible, and fairly common, to write 
loops that do not terminate, or that generate infinite garbage. 
If you invoke your request, and the cursor never leaves the 
minibuffer, and *G seems to have no effect, you are in a loop 
Hit QUIT, and use the program_interrupt {pi) Multics command to 
reenter Emacs. If you are singularly unfortunate, you get: 

lisp: (nointerrupt t) mode, unable to accept interrupt 

in which case you are stuck in the process of generating infinite 
garbage^ In this case, you must release, and your editing 
session is lost. If you are more fortunate, you will get your 
screen back, with the cursor at the place your function left it 
9ften, by looking at exactly where it left it, you can get a good 
idea of what kind of thing was giving your program a hard time. 

If you get messages from Multics that tend to indicate that 
there is no more room in your process directory, you are probablv 

a^riAra-f- inrr an infinite »*,„wU.~.— » e i i .• _ • * . .. *"\ ■* 

= 3 ».. ....^.i^e uuuioci. ui iiiies, i.e., an lnnnite ©utter. 

Another thing that can happen is you might expose some bug 
or what you believe to be a bug, in Emacs, or worse yet, Multics 
Lisp. Use the trouble report forwarding mechanism to describe 
what you encountered and why you think it is a bug. 

You can also destroy the editor environment by bad coding. 
This is particularly true in running compiled code that was not 
checked out interpretively (i.e., via ESC *Z). Storing into 
nil is one common way to do this. If the entire editor seems 
broken, and the redisplay does not even show the screen, i-hie < c 
what you have done. Quit and release and start all over 'again. 

A function called debug-e is called as: 
ESC X debug-e CR 
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It sets "(*rset t>" mode and other Lisp debugging aids, and 
unsnaps all "lisp links". It also reverts to native Maclisp 
QUIT/pi handling. To use this, however, you must be familiar 
with the debugging features of Multics Maclisp. 

To get the value of. a global variable to be printed out, 
say, fill-column, type: 

ESC ESC progn fill-column CR 

Be careful r for values typed out are in octal. . 

A. Lisp code debugging facility within Emacs, called LDEBUG, 
or Lisp Debug mode, allows for the setting of breakpoints, 
dialogue with Lisp within Emacs, tracing, and so forth. See 
Section 4. 



COMPILATION 

All production Multics Lisp programs are compiled. This 
results in a tremendous performance improvement, both for the 
user and the system. Compiled Lisp programs are executed 
directly by the Multics processor; interpreted programs are 
interpreted by the Lisp interpreter. Emacs is compiled Lisp. 

The Lisp compiler is a Multics program that can be invoked 
from command level. It has the names lcp and lisp_compiler . To 
compile a program named myfuns.lisp, you say: 

lcp myfuns 

to Multics, and you get an object program named "myfuns", which 
can be loadfiled, in the working directory. 

The compiler diagnoses Lisp syntax errors. It warns you of 
implied special variables (if you did not declare a variable 
special, and it is not a local variable in the function in which 
it was referenced, you probably made a mistake. All global 
variables should be declared for this reason,* e-macros declares 
the provided ones.) 

At the end of compilation, the compiler prints out the names 
of functions referenced in the code but not defined in the file. 
This is normal; however, you should inspect the list it prints 
out to see if any are ones that you thought you defined; if so, 
you have a problem. Check also for ones that are obvious typing 
errors. 
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While editing a large extension program, you may wish to 
load only the function that you are looking at on the screen into 
the editor environment. The function compile-f unction, on ESC A C 
in Lisp mode, compiles the function you are looking at (whose 
start is found by ESC A A from where you are now) into a temporary 
segment in the process directory. It then loads the object 
segment, and displays the compiler diagnostics via local 
printout. It should be used with the cautions noted below. When 
using it, remember to write out your changes, and recompile your 
whole program, because a program incrementally debugged in this 
mode gives the impression that it is working properly when it is 
only doing so in the current editor environment. 

Compiling functions via ESC A C is often advantageous; the 
compiler produces diagnostics that help locate errors that you 
might not have encountered until your function ran, or perhaps 
not even then. ESC A C effects compilation and loading of the 
current Lisp function into your Emacs environment by loading the 
Lisp programs that constitute the Multics Lisp Compiler into your 
Emacs environment and invoking them. The loading happens only 
the first time Lisp mode ESC A C is used in an invocation of 
Emacs, and Emacs tells you when it is doing this. Emacs also 
loads the correct version of the e-macros include file during 
this first invocation. 

Forms compiled by Lisp mode ESC A C are treated as though 
they had been encountered by themselves in a source file being 
processed by the Lisp compiler. As viewed by the Emacs user, 
successive compilations of functions via ESC A C appear to be 
successive invocations of the Lisp compiler. This, however, is 
not an accurate description of what is taking place. As viewed 
by the Lisp compiler, which is then "living" in the Emacs 
environment, it is compiling one large source program consisting 
of many functions (i.e., successive uses of ESC A C); all editing 
activity "between ESC A Cs" is irrelevant to it. Thus, invoking 
ESC A C for a Lisp macro definition defines that macro for all 
functions compiled by ESC A C in that invocation of Emacs from 
that point on. Therefore, you must ESC A C Lisp macro definitions 
if you intend to compile or evaluate function definitions using 
these macros. (In the case of macro definitions , ESC A C 
(compilation) is equivalent to to ESC A 2 ( evaluation ) . Macro 
definitions, whether ESC A Ced or ESC A 2ed, are accessible to 
functions ESC A 2ed or ESC A Ced.) 
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Similarly, Lisp "reader macro" character definitions must be 
evaluated if they are to be utilized by ESC A C. Declarations of 
special variables (other than those declared for you in 
e-macros.incl.lisp) should also be ESC A Ced ( not ESC A Zed) if 
they are to be respected by functions being ESC A Ced. Often, if 
you fail to do this, the compiler (ESC A C) automatically detects 
undeclared use of special variables and warns you; however, in 
certain cases (most notably binding them via let), it does not , 
and erroneous code results. 



The compiler accumulates compilation diagnostics in the 
uuj. t&r nainevx Compixer Diagnostics," Diagnostics for each 
application of ESC A C are displayed as local display. 

DOCUMENTING REQUESTS 

The automatic documentation system (apropos, ESC ?) 
provides customized Emacs request documentation. Documentation 
for^ supplied requests is kept in a special file in the Emacs 
environment directory.. You can provide documentation for your 
own requests by placing a string, which is that documentation, as 
the "documentation" property of the symbol that is the request 
being documented. For instance, if the symbol 
remove-every-other-word has the documentation property of: 

"Removes every other word from the sentence in which the 
cursor appears." 

this information is displayed by ESC ? when used on some key set 
to remove-every-other-word, or by: 

ESC X describe remove-every-other-word CR 

Documentation properties are assigned most conveniently via 
the Lisp- special form "defprop", whose general syntax is: 

(defprop SYMBOL WHAT PROPERTY) 

This assigns the symbol (SYMBOL) a property (PROPERTY) of WHAT. 
The defprop is a special form because the actual symbols 
appearing in the form are used; they are not variables, as in "(+ 
a b c ) " . Thus , 

(defprop Joe Fred father) 
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gives the > symbol "Joe" a "father" property of "Fred". (The 

-ouJSrSS- lS f a ,?Pecial-forni way of doing the same thing as the 

putprop function, but it is a special form because its 

2ll7T* f^ n0t f ° rmS i° be ^a^ted to produce symbol! 
whose properties are to be dealt with, but the symbols 
themselves). To use defprop to establish Ernies reques? 
documentation, place forms like: -equest 

(defprop remove-every-other-word 

"Removes every other word from the current sentence. Will 
not work on sentences ending in »"?»*. For indented 
sentences, use $$remove-other-word-f rom-indented-sentencess. 
$$$ is a powerful, dangerous, command." 

documentation) 

Note several things about the documentation string: 

1. It does not need to end in a newline, and can contain 
newimes. 

2. Quotes (") inside of it must be doubled. 

3. The string "$$$" will be replaced by the key being 
asked about (e.g., "ESC A Z n or "ESC I 
remove-every-other-word") at the time the documentation 
is displayed. 

4. The keys used to invoke other requests can be 
referenced by stating two dollar signs, the name of the 
request, and one dollar sign. Thus 

SSQO-tO-end-Of-1 inp« annate -.- aw _•_ .' 

■ ■-. , -- v ~ t ,f-**'- * as) a in most 

environments; the point of this and the ■ previous 
paragraph is to make documentation expansion 
independent of a user's key-bindings. 

The entire documentation string is "filled" (ESC Q) after 
all command-name substitutions are made; thus, the placementof 
newimes in the documentation string is ignored. Two conlecutiSe 
newimes, however, are preserved, and th2s, lines can be let of f 
for examples, etc., by surrounding them with blank lines. 

«i ^JVi 19 * 1 * 1 ? more efficient, but clearly less readable, to 
place the defprop documenting a request before the defun definino 
uhe request itseir. The defcom facilTty-Ein also be used to 
document requests; see "Defining Requests With defcom" below 
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WINDOW MANAGEMENT 

Although buffers appear in windows on request, and are 
switched between automatically by the redisplay when you switch 
windows with A X A 0, A X4 , etc., there are times when you may want 
to take advantage of multiple windows explicitly. Good examples 
in supplied code are RMAIL reply mode and the comout-command 
( A X A E). 

Most of the extensions of interest are ones in which the 
extension writer wants to place some information in a buffer, or 

_t • _ —.-. — — ——.» ™ — — _ U,,-P £„ «. fc-*v. Vsttai in f ny-mp> +• i i-in t"i1 a /»»/■! in 1^ / *» _ O _ . 
gXSB' U4CyaiC auuic uutlCL WW uo»S mi.wiiu6u*«ii £*a***»-_<- -•• -— v — -3-r 

RMAIL. reply) and then display that information in a window. 
Usually, all that is required is to "go to" that buffer (e.g., 
with go-to-buffer or go-to-or-create-buf fer ) . The redisplay 
"finds*, the editor in that buffer at the time of the next 
redisplay, and replaces the contents of the selected window on 
the screen. Such requests are called autophanic (self-showing). 
Examples are A XB (select-buffer) and A X A F (find-file). 

However, some requests set up buffers in some window other 
than the current window, usually for multi-window operations such 
as mail reply, so as not to disturb the contents of the current 
window. They are called heterophanic (other-showing). The 
standard examples are dired-examine, mail reply, and 
comout-command ( A X A E). All the examples given are sub-requests 
of larger, autophanic requests. 

Heterophanic buffer behavior is provided by the function 
find-buf fer-in-window.. It takes as an argument a buffer-symbol 
(Lisp symbol representing a buffer). That buffer is created if 
it does not now exist, and is gone to, as if go-to-buffer had 
been used. If Emacs is in single-window mode, the effect is the 
same as that of go-to-or-create-buf fer . In two-window mode, that 
buffer is put on display as follows: 

a If it is already on display in some window, it is left 
there. 

b If it is not , it is put on display in some other 
window, one in which the cursor is not , and the cursor 
moves to that window, as if a A X A had been done. The 
least-recently used window is chosen. 
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Thus, on printing terminals and in single-window mode, the 
effect of find-buffer-m-window is indistinguishable from that of 
go-to-or-create-buffer. in multi-window mode, it is equivalent 
to go-to-or-create-buffer, displaying that buffer in another 
window, 

You must not use f ind-buf f er-in-window to place a buffer on 

f •% ? C r! en ? nce . l ou have alrea dy gone to it? if you think of 

find-buff er-in-window as a kind of go-to-or-create-buffer, you 

will find no need for doing so. 

An extension must establish multiple windows if it needs 
them; no current Emacs code requires multiple windows, although 
the tacilities mentioned above are more useful when already in 

Most extensions that place an auxiliary buffer on display 
via f ind-buf fer-in-wmdow provide some request to return to the 
main buffer (e.g., the RMAIL Incoming Message buffer, the 
v? s e f-nH°S ^ lch . AXA ? » as ^sued, etc.). If you enter a buffer 
via find-buffer-m-window, you should probably return to the 
Zk J* f° m whe ? ce .y° u can >e via f ind-buf fer-in-window as well; 
the effect of this is to restore not only the original buffer 
but also the original window. Thus, save-excursion-buf fer cannot 
f?n* w? effectively to return from buffers entere d via 
.« 7? • r_1 w" W v nd< ? w l an attem Pt to use save-excursion-buffer 
results ^ in both _ windows' showing the same buffer, since the 
sexectea winaow (i.e.., the cursor-bearing window) is" changed and 
a new nut fer selection means a new buffer in that window. 

k, ff The T Q v key se< 3? ence should be used to exit auxiliary 
buffers used by extensions to return to their main buffer, and 
usually switch windows as well, if the multiple-window strategy 
outlined above is used. ot - c yjr 

w P °P" U P window mode, in essence, makes all requests 
heterophanic. Requests or subrequests that are naturally 
f?«S r JP55 niC - ne ? d " ot wo "Y about pop-up window mode, because 
I™ r in ' SindOW tak I S the a PP^priate action in either 
h*L"? ° 2 on -P°P-"P mode. However, if proper heterophanic 
behavior under pop- up windows is desired, naturally autophanic 
requests and subrequests must call a window-management primitive 
to ootam heterophanic behavior in pop-up window mode. This 
primitive is called select-buffer-window. It takes two 
arguments, a buffer-symbol, and a "key" that gives pop-up window 
management a preferred window size. 
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In non-pop-up window mode, select-buffer-window is 
equivalent to go-to-or-create-buf f er , and the key is ignored. In 
pop-up mode, it is equivalent to f ind-buf fer-in-window, with the 
key suggesting the new window size. 

The following values for the key argument to 
select-buffer-window are accepted. They specify the window size 
in pop-up mode if the window does not exist already: 

any* number 

That many lines:.. 

'cur size 

Make a choice based on the current number of lines in 
the buffer. 

nil 

Chooses some reasonable fraction of the screen. 

' cursize-not-empty 

Same as nil if the buffer is empty; same as 'cursize if 
it is. not. For example, A X A F uses this, because you 
can type into a new buffer. 

'default-cur size 

If this buffer has never been displayed before, makes a 
choice based on the number of lines. Otherwise, uses 
the same size was chosen last time. 

The f ind-buf fer-in-window can not be used to display the 
"current buffer" heterophanically. If you attempt to do this: 

(f ind-buf fer-in-window current-buffer) 

you find it appearing in both the old and new windows, for the 
window manager finds that you were in this buffer in the current 
window (a truth) before you went to another one (you had to go to 
another one, as per heterophanic behavior), and indicates that 
the current buffer is to be displayed in the old window as well, 
for that was the last buffer you were in in that window. To 
avoid this, use select-buffer-find-window (of two arguments, the 
buffer and a key as for select-buffer-window) if heterophanic 
display of the current buffer is needed: 

(select-buffer-find-window current-buffer nil) 

This is rare, since v ou seldom go to a buffer and then want to 
f ind-buf fer-in-window it; in Emacs, only A X A E does this. 
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Since all things using these features are moderately 
sophisticated, only an outline of an extension using them is 
given here. It is a typical sub-subsystem (e.g., dired) that 
sets itself up m an autophanic buffer display, with specific key 
bindings, etc., and has a heterophanic subdisplay by which it 
displays a "menu" in addition to the main display: 

(defun unusual-mode () ;Setup function for this mode 

(go-to-or-create-buffer (maknam 

(explodec "Unusual buffer"))) 
(set-key *ESC- A S * unusual-mode-show-menu) 
(select-buffer-window current-buffer nil) 
( register-local-var ' unusual-mode-buf f er-to-return-to) 



(declare (special unusual-mode-buf f er-to-return-to) ); for compiler 
(defun unusual-mode-show menu () 

(setq unusual-mode-buff er-to-return-to current-buffer) 

/*• >a w *r • • „ ;save buffer 

( find-buff er-m-wmdow 'Unusual -Menu) ;Display menu 
(set-key ' r 'unusual-mode-select-item) ;Set key bindings 
(set-key ' A X A Q 'unusual-mode-menu-return) 
(insert-string "Unusual menu delicacies") ;Fill it up 
;; Will not actually be displayed until request finishes. 

(go-to-beginning-of -buffer) 

(setq current-buffer-mode 'Unusual/ Menu 

buffer-modified-flag nil read-only-flag t) 

(defun unusual-mode-menu-return () 

(f ind-buffer-in-window unusual-mode-buf f er-to-return-to) ) 
;;Return to calling buffer. 

The following are several primitives available to deal with 
windows by window number. The topmost window on the screen is 
window number 1; the next one down, if any, is number 2, etc., 
(tfte minibuffer and mode line do not count as windows). The 
selected window is the one in which the cursor currently appears. 

selected-window 

This variable contains the number of the currently 
selected window. Do not attempt to setq it to select' a 
window; use select-window instead. 

nuwindows 

This variable contains the number of windows on the 
screen; do not attempt to setq it to create or delete 
windows; use delete-window and the A X2 and A X3 
functions to do these things. 
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select- window 

This function (of 
selects that window 



one argument, a window number) 
(as A X4 with an argument does). 



delete-window- 

This function (of one argument, a window number) 
removes, that window from the screen, distributing its 
space to the other windows. 

buff er-on-display- in-window. 

This predicate function (of one argument, a 
buffer- symbol) returns truth if the specified buffer is 
on display in some window on the screen. If used as a 
function , i.e., the- value returned is inspected, the 
returned value the window number in which the specified 
buffer is on display (if it is not on display, the 
symbol "nil", representing falsity, is returned). 

window-info 

This function (of one argument, a window number) 
returns information about that window. The information 
is. in the form of a piece of Lisp list structure, which 
can be interpreted by the Lisp list destructuring 



J. unv. u J.O11; 



a33LUUi4Vj unau xiii-w uas uiic 






window-info, the following forms return the information 
as follows: 



(caar info) 

(cdar info) 
(caddr info) 

(cadddr info) 



=> 

=> 
=> 



The top line-number on the screen of 
the window. The topmost' is 0. 
The number of lines in the window. 
The buffer-symbol of the buffer on 
display in the window. 
A string duplicating the contents of 
the "cursor line" of the window, 
including its newline character. The 
cursor line of a buffer is that line 
where the cursor is (if it is in the 
selected window) or would be if that 
window became selected (e.g., with 
A X0). 

window-ad just -upper 

A- function of two arguments, the first a window number, 
and the second a signed number of lines to move its 
upper divider-line down (negative is up). 



window-adjust-lower 

Same -as window-adjust-upper , 
divider line. 



but deals with lower 
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WRITING SEARCHES 

Several functions aid in providing search-type reauests 

search s?rino« S %?* ^ the Search Strin 3< P^ide lelfuli 
search strings, and announce search failure in a standardized 
way. All supplied Emacs searches use them, "anaaraizea 

get-search-string 

Takes one argument, the prompt. The prompt should 

£rJ£5i2 ,£ W ° rd . nsearch "- T he get-search-string 
prompts the user for a search string, which the user 
must terminate with a CR, and returns it as a string. 
If the user gives a null string, the last search strinq 
is used and echoed. The last search string is set to 
the returned string for the next defaulting. 

search-failure-annunciator 

Caus f;S the " Search Fails." message to appear in the 
■ S£?i I I ' , a command-quit (a 6 ) to be performed. 

This aborts any keyboard macro collection or execution 
in progress. 

: nt . aT .? hen writi £9 a search-type request, you should provide two 
iS f C ! S ' 3 " command "' w ^ich calls the above two primitives 
letch nrf™?f- h Pr £ 01 ?i Ve ' alS ° Called b ? the "command"? The 

l«S?n„ P Si ? nJ 1V f S° uld tetUrn t (truth) if the search succeeds, 
leaving point at the # proper place, as the search defines. If the 
search fails, the primitive must return nil (falsity)? and leave 
point where it was when the primitive was invoked? 

A simple implementation of a wraparound search, below first 

I?°tha! r ?^ in V° th V nd „ ° f the bSffer for the search strn|! 
«nM™? k Sf 11: .9oes to the top and searches again. It is nit 
™?if , b ecause it needlessly scans farther than the original 

Searching S ? artin ? from . th * top. Using point>mark P 9 and 
searching a line at a time would be very expensive dn* %« 
pomt>markp's expense. Searching a line* 1? a time ulinq 
forward-search-in-line and mark-on-current-line-p would Se 
acceptable but more complex than this example need be. For a 
search that is .probably going to be used onlyas a user interface 

ifff;i.n? 0t p in i? rna i ly) '- this implementation is adequately 
?f f ^ en £: * eca11 that with-mark releases its mark and Returns 
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Here is the internal primitive for wraparound search: 

(defun wraparound-search-primitive (string) 

(wlth-mark m jRemember starting point 

(if (forward-search string) ;Look to end of buffer 
t ; Return truth 

else 

(go-to-beginning-of -buffer) 
(If (forward-search string) jrLook from top 
t 

else 

(go^to-mark m). ;Return to orig. place 
nil))})) r Return falsity 
Zp with-mark and this function 
?? return the value of the outer "if'' 

The request for calling the primitive: 

{defun wraparound-search ( ) 

(if (not (wraparound-search-primitive 

(get-search-string "Wraparound Search: *))) 
(search-failure-annunciator) ) ) 

The wraparound-search request should have some key bound to 
it if this type of search is to be made available from the 
keyboard. 

CALLING MULTICS COMMANDS 

In some extensions, especially those like DIRED that 
manipulate the Multics environment, you must call Multics 
commands, or execute Multics command lines. 

Multics command lines are strings submitted to cu_$cp for 
execution. This is the Multics agency to which the "e" requests 
of the Multics edm and qedx editors, the ".." requests of 
read_mail, sendjnail, and debug, and other subsystems submit 
command lines. The two primitives for executing Multics command 
lines are: 

e__cline_ 

Takes, one argument, a string, which is passed to cu_$cp 
for execution. No reattachment of output takes place. 
If the command line produces output, it messes up the 
screen. This should only be used when no output is 
snfirinat-ad ar>A choiild bi» n.qpd th^n in oreference to 

comout-get-output , since it is much faster. 
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comout-get-output 

Takes any number of arguments, which may be strings or 
symbols, and catenates them with one space between them 
to form a Multics command line, facilitating things 
like: 

(comout-get-output 'delete this-seg '-bf) 

Reattaches user_output and error_output during the 
execution, rerouting them to a process directory file. 
When the command execution completes, the contents of 
the current buffer are obliterated (!) and the 
temporary file read in to it. This is the primitive 
that comout-command ( A X A E) uses; e_cline is used by 
comout-get-output internally. 

These primitives set up a condition handler that catches all 
abnormal Multics signals and aborts to a second Multics command 
level with a message if one occurs. However, requests for input 
by these command lines cannot at this time be dealt with well 
In the case of e_cline_, the user gets the query in raw teletype 
modes, and has to answer it in raw, nonedited teletype modes. In 
the case of comout-get-output, the query never appears, having 
been routed to the temporary segment, and the user's process 
hangs since the user, having never seen the query, does not know 
to respond. 

MULTICS ERROR TABLE 

To get the value of standard Multics error codes, from 
error^table_, into a program to see if a given Multics interface 
has in fact returned it, the function "error table " (with 
underscores, not hyphens) is used. Its single argument is a 
symbol, whose name is the name of the error_table entry whose 
value is sought, and the returned result is that value, or 1 if 
it is not a valid entry. 

The error_table_ function optimizes finding the same name 
over and over again, so you need not go through machinations to 
save an error_table_ value computed by these means. An example 
of the use of error_table_ follows: 

(let {(status-result (hcs_$get_user_ef fmode dir entry Bn ))) 
(if (not (= (cadr status-result) 0) ;the return code 
(if (= (cadr status-result) 

(error__table_ ' incorrect_access) ) 
(display-error-noabort "Warning: not checking 

access") 
else 

(display-com-error (cadr status-result) dir ">" 
entry)))) 
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I EMACS ERROR SYSTEM 

Emacs has its own error system, with several functions 
available. They provide more error information than do the 
display-error and display-error-noabort functions (which simply 
take a string argument), because they are tied into the Emacs 
Error Table. 

report-error 

aborts the current computation and prints an error, 
report-error-noabort 

prints an error without aborting, 
add-error-code 

adds an entry to the Emacs Error Table 
error-table 

gets a standard Multics error code and returns the 

numeric value. 

Their syntax is: 

(report-error error-code error-information) 
(report-error-noabort error-code error-information) 
(add-error-code error-code error-string) 
(error-table segment offset) 



where: 



error-code 

is a symbol representing an entry in the Emacs Error 
Table (e.g., ' beginning-of-buf fer) , or is a standard 
Multics error code, or is a symbolic Multics error 
code, e.g., error_table_$moderr. 

err or- in format ion 

is any number of objects to print in the error report. 

error-string 

is a string describing the error. 

segment 

is a Multics error table segment. 

offset 

1 S Cue syuiuuilt name \j i. an Silul i»a.w.i.S Sti i. j. jr , e.vj., 

"moderr" in error table smoderr. 
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Defining Rgauests With defcom 
de£inu!on de ol 0m t ig 0r £u ff|i^:^f2^) facility simplifies the 

of nim er!c arguments 1 22t^t?frepitrtiln rg ™r„u;er?. n9e " CheCkin9 
cross-connecting symmetrical functions vif „2^" C ar 9 umen ts, 
and other features. I ' ons vla negative arguments, 

environment; 'not 3 IL^oflmLs' "internal 7 ^ ^ E ^ CS -tension 
to use it. Perusinn \hl vT internal code has been converted 

defcom's use intlrmLed w?th C oldfr UrCe ' ?° U wi ^ find examples of 
request functions! ** exam P les usi "9 defun to define 



to be used af Imacs relief* -V*' , *•«»*«* function, actually 
be used- by these Lnc?ions 'shSufd^, 1 -??^ 3 ^ 1 ^^ f ™<=tions to 
Emacs requests defined w^h defun" I? 1 *\ d ? iin * d v ^h defun. 
with def<?om produce better di^ c ^ n w ? rk ' but those defined 
Defcom is a technique wherebv ?£fn *"* 2 f * er more Matures, 

automatically, ^functions* defln^ w'? 3 ^?^" 5 are generated 
from other functions "as Sell.. defC ° m Can be called 

*-t... To def ine a function with defcom. „ ca d „ f ,__, , . 

UCiun ' ana supply no Lisp argument list":" """"' iI15teaa ° £ 

(defcom one-word-from-beginning 

(go-to-beginning-of -buffer) 
(forward-word)) 

suppliel by h %la S cf?g eS betwe°e r n ?he fun'??' ° Pti ° nal £eat — a « 
oode, various keywords all «f C k-°J! 2 am ? and the fu "ction 

character, and slmeo! which take . ™ t" 631 " with the " £ " 
as lists. wnicn take optional arguments, expressed 

for In a , m0 f';fe mn °" ?ptional specification is Snumeric-^rg.-e^ 
argument:' lhe"ke^ord"inum«L t0d ° " ith a S «PP"^ numeric 

^Irocelsing^yS ™ ' ^ '-"elf che^Lg 

irea laI C l f L" I9 ^ tv - S - re ^ eC ^ aS =«e? 1 ^is^r^ 

default if tnumeric-argument is not given. 
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Signore 

h numeric argument is ignored. 

Srepeat 

If the argument is positive, the request is repeated 
that many times. 

& pass 

The value of the Lisp variable "numarg" is set, as in 
nondefcom requests 

In- addition to the major processing type, optional bounds 
can be specified by the keywords Supper-bound (Sub) or 
Slower-bound (Sib). These, in turn, must be followed by either 
an integer representing the bound, or the keyword Seval followed 
by an expression to evaluate at the time command execution is 
attempted, which then produces a value (such an expression is 
called an "teval expression".) Here are some examples of 
Snumeric-argument specifications: 

Srmmeric-argument (Spass) 






^Srepeat Slower-bound 1 

Supper-bound Seval (+ max-foos 2)") 

Snumeric-argument 

(Spass Supper-bound 15.) 

Another optional function which specifies what 'to do with a 
supplied numeric argument is Snumeric-function. The 
Snumeric-function function doesn't actually do anything with the 
supplied argument. Instead, it causes a different request to be 
executed if the original request is given a numeric argument. 

Here is an example of a Snumeric- function function 
definition:- 

{defconr global-print 

Snumeric- function global-regexp-print 
. .• . y 

It can be invoked as: 

A U A XS 

j in which case the global-regexp-print request is executed instead 
of the- global-print request. 
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A request defined with defcom may elect to receive Lisp 
arguments, values that are to be prompted for or supplied as 
extended request arguments. They can be provided automatically, 
and prompted for, by the Emacs command reader, and supplied as 
Lisp arguments to the request function. Instead of a normal Lisp 
argument list, the keyword ^arguments (or &args or &a) are 
followed by a list of argument specifications, one for each Lisp 
argument to be supplied. 

Each argument specification consists of the Lisp name of the 
argument, _ i .e. , the name of the variable to be referred to inside 
the function, and any number of argument qualifiers, separated by 
spaces. Each argument qualifier can consist of several tokens, 
as necessary. Argument qualifiers specify the prompts, defaults, 
etc., for an argument. An argument specification may also be 
given as the name of the variable alone, as opposed to a list of 
it and qualifiers. In this case, it is equivalent to having its 
own name as a prompt for its value. 

When a defcom-def ined request is invoked as an extended 
request, (i.e., via ESC X), the Emacs command reader checks the 
type and number of request arguments supplied and necessary, and 
prompts for those not supplied, or defaults them as specified. 

When a defcom-def ined request that has arguments is invoked from 
a key, it is as if it were invoked as an extended request with no 
request arguments given, and all are either prompted for or 
defaulted. 

The valid argument qualifiers are.: 

tstring 

& symbol 

^integer 

Specifies how the argument, when read by ESC X or 
prompted for, is to be converted before being passed. 
Only^ one of these is valid in a given argument 
specification, and tstring (i.e., no conversion) is the 
default. 

fidefault 

Must be followed by either a string, symbol, or 

integer, as consistent with the expected data type for 

this argument, or an &eval expression. Specifies the 

default value to be used if this argument is not 

supplied, or a null response is given to a prompt for 
this argument, if any. 
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^prompt 

Specifies the prompt for this argument, if not supplied 
via ESC X. Prompts are put to the user before defaults 
are evaluated or used; a null string causes the 
&de fault value to be used. An Stprompt is followed by a 
prompt, string (in quotes), or an &eval expression, and 
one of the two optional keywords NL or ESC, specif iying 
the prompt terminator (NL is the default). 

&rest-as-list 

Valid only for the last argument. Causes this variable' 
fed be. given, as a value-, a list of all of the remaining 
supplied arguments. rf &rest-as-list is used, the 
caller of this function from Lisp (including start-ups 
written by not-Lisp-conscious users) must know that the 
number and organization of Lisp arguments is different 
from the apparent argument array given to ESC X. 

Strest-as-string 

Valid only for the last argument; causes all remaining 
arguments to be supplied as a single string to the 
function, as they appeared to ESC X, with spaces and so 
forth included. Same cautions as for &rest-as-list 
apply, 

A function definition that accepts three arguments follows: 

(defcom replace-n-times 
Sarguments 
((oldstring fcstring &default Seval 

(get-search-string "Old: ")) 
(newstring &string &prompt "New String: " NL) 
(count ^integer &prompt "How many times? " NL 

tde-fault 1)) 

(do-times count 

(if (hot (forward-search oldstring)) 

(search-failure-annunciator) ) 
(do-times (stringlength oldstring) (rubout-char) ) 
(insert-string newstring))) 

It can be invoked as; 

ESC X replace-n-times Washington Lincoln 2 CR 
or: 

ESC X repiace-n-times CR 
in which case all arguments are prompted for, or: 
set-perm-key A Z9 replace-n-times 
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followed by striking A 29 at some time, prompts for all arguments, 
too. This function is defined so that it can be called from Lisp 
as: 

{replace-n-times "this" "that" 17) 

or whatever, i.e., it is a Lisp function of three arguments. 

When defcom-def ined requests are reexecuted by A C, they are 
repeated with identical arguments. This is what makes 
search-repetition by A C work. 

In addition to numeric arguments and request arguments, 

defcom can be used to specify prologues, epilogues, | 

documentation, cleanup functions, and negative functions of | 
request functions.- 

Prologues are functions or code to be executed before any 
arguments are prompted for, perhaps to check for valid 
circumstances for calling this request. Prologues are only | 
executed once. If the request is repeated because of a numeric j 
argument, prologues are not repeated with each iteration. | 
Prologues are specified by the keyword ^prologue, and the name of 
a prologue function or an teval expression. 

Epilogues are functions or code to be executed after each ! 
invocation of the request. If the request is repeated because of 
a numeric argument, epilogues are repeated after each iteration. 
Epilogues are specified by the keyword ^epilogue, and the name of 
an epilogue function or an &eval expression. The epilogue 
function takes three arguments and is called as follows: 

(function prologue-info result laatp) 

where: 

prologue-info 

is the value returned by the prologue function, or nil if 
there isn't one. 

result 

is the value returned by the request itself on this 
iteration. 

lastp 

is non-nil if this is the last (or only) iteration. 
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Documentation is specified by the keyword ^documentation (or 
&doc) followed by a documentation string subject to the same 
rules as given above under "Documenting Requests". 

Cleanup functions are functions or code to be executed if 
the request is aborted.. Cleanup functions are specified by the 
keyword icieanup, and the name of a cleanup function or an Seval 
expression. The cleanup function takes one argument and is 
called as; follows:: 

(function prologue-info) 

where : 

prologue-info 

is the value returned by the prologue function, or nil 
if there isn't one.. 

Negative functions are functions or code to be executed if 
the request is given a negative numeric argument: the negative 
function is given the negative numeric argument made positive. 

nS^ouivc Lunwiiuiia at c a^eciiieu uy tiie Keyword 

&negative-f unction (&nf), followed- by the name of the appropriate 
function, or forms, terminated by &end-code. The following is an 
example of the use of some of these features: 

(defcom forward-topic 

Stdoc "Goes forward one or more topics. See also 

$$backward-topic$ . " 
Snumeric-argument (&repeat) 
«negative=f unction backward- topic 
(with-mark m 

( forward-search "Topic : : " 

Emacs determines whether a character should stop echo 
negotiation by checking a list named "nobreak-f unctions" . The 
defcom keyword &no-break adds the command being defined to the 
list. Keys bound to symbols on the list are echoed by the FNP, 
and do not interrupt the process (unless at end of line). 

Another defcom keyword, icompletions (or &completion, &comp) 
provides minibuffer prompt completions. It allows any 
defcom-def ined command to define completions that should be in 
effect for a given argument. The ESC SPACE request, 
complete-command, uses these completions to complete minibuffer 
input. An example of the ^completions keyword is below: 
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(defcom new-function 

^arguments ( (argl &prompt "What is arg one? " 
^completions '("one" "two")) 
(buf tprompt "OK, and in what buffer? " 
^completions known-buf list } ) 
(minibuffer-print "Buffer is " buf ", argl " argl ".")) 

The argument after the ^completions keyword is evaluated at the 
runtime of the function. The current list of completions is kept 
in the lisp variable completion-list. 

UNDOING A REQUEST 

The undo-prefix command, A \, sets the variable "undo" to t 
which causes the next function called to attempt to do the 
reverse of its usual action. Defcom-def ined requests make use of 
this through the & undo- function <&undo, ^inverse) keyword Its 
syntax can take one of six forms: 

&undo (&pass) [or the equivalent &undo &pass] 

&undo Uignore) [or the equivalent &undo Signore] 

Sundo (^reject) [or the equivalent tundo Srejectl 

&undo function-to-call 

&undo (lisp expression to call) 

£undo &code lisp expressions &end-code 

If the defined request is prefixed by *\ when called, then the 
special action is taken. Thus, if any of the last three forms is 
used, the function sn^rifio^ af+*y fk« i»~.. — -j i- ---I1--3 -• 

.the defcom-def med request; if the first form is used, the 
variable "undo" is set to t and no special action is taken. This 
would _ mean, for example that "&undo &pass , " used in the 
definition of re-execute-command (*C), causes the sequence A \ A C 
to attempt to undo the last request executed. The second form 
causes the undo prefix to be ignored. The third form causes the 
default action, rejecting any undo prefix given. 
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A DETAILED EXAMPLE OF A FUNCTION DEFINITION 

The following example of a function definition for the 
string-search command uses many of the keywords described in this 
section: 

(defcom string-search 

Sdnverse reverse-string-search 

targuments {(search-string &string sdefault 

fceval (get-search-string 

(search: numeric-prompt 

— ——---3 •- — ss— — -- I I I I 

SproLogue search : command.-prologue 
Snumeric-argument &repeat 
&negative- function reverse-string-search 
tepilogue search:command-epilogue 
Scdeanup search: command-cleanup 
(forward-search search-string)) 

The Sdnverse keyword indicates that A \ A S calls the 
reverse-string-search command. 

The iarguments keyword indicates that A S takes an argument 
named "search-string" (the string to search for), which defaults 
to calling the get-search-string function in order to get the 
string from the user by a prompt. 

The &prologue keyword indicates that the prologue function 
named "searchtcommand-prologue" runs before the first call of the 
forward-search command. In this example, the prologue function 
returns a cons of the number and a mark set at the place from 
which the search began. 

The Scnumeric-argument keyword indicates that ESC N A S calls 
the forward-search command N times. 



The &negative-f unction keyword indicates that ESC -N A S 
calls the reverse-string-search command, with a numeric argument 
of N. 
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The ^epilogue keyword indicates that the epilogue function 
named "search:command-epilogue" runs after each call of the 
forward-search command. In this example, the epilogue function 
does various bookkeeping operations for the forward-search 
command, deciding whether the command should continue or no^ . 
When the search fails, it aborts the command. The epilogue 
function is called with three arguments, which are as follows: 

prologue-info: 

in this example, whatever the Sprologue function 
returns, which is a cons of a number and a mark; used 
by the epilogue function to store the iteration count. 

result: 

, in this example, whatever the forward-search function 
returns, which is non-nil if the search was successful; 
used by the epilogue function to decide whether to let 
the function continue or not. 

lastp: 

in this example, non-nil if this- is the last iteration 
of the forward-search function; used by the epilogue 
function to decide whether to set a gratuitous mark if 
the search failed. 

The Sccleanup keyword indicates that the cleanup function 
named search:command-cleanup" runs when the forward-search 
command is aborted. In this example, the cleanup function 
decides whether the forward-search command should go back to the 
beginning or not. The cleanup function is called with one 
argument, prologue-info, which is modified by the epilogue 
function as described above. 

The forward-search command is the actual code in this 
function definition of the string-search command. In this 
example, it s just one function call, but it could be several. 

You should note that most of the keywords are interpreted by 
the Emacs command loop. This means that they can be ignored when 
a command is called directly as a function, as it is in extension 
code. The mam exception to this is the ^arguments keyword. 
This keyword sets up an argument list for the function, so the 
function requires that those arguments be given explicitly in the 
function call. 

In the example above, this means that calling string-search 
is equivalent to calling forward-search, because all 
string-search does is call forward-search with its arguments. 
All of the other functions are executed before or after 
forward-search is executed, without its knowledge. 
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SECTION 4 
LDEBUG MODE 



Emacs LDEBUG mode (Lisp Debug) provides an interactive Lisp 
environment designed for the debugging of Emacs extension code" 
Facilities are provided for tracing the Lisp stack, breakpointing 
?S2»^ and interacting with the native MacLisp trace facility. 
LDEBUG mode is specifically optimized for multiple-window 
interaction. 



LDEBUG BUFFER 



The heart of the LDEBUG mode facilities is the LDEBUG 
buffer. The buffer named LDEBUG, when created by 1 debug mode 
(either in response to a breakpoint's being executed, a trapped 
Lisp error, or the explicit "ldebug" extended request), evaluates 

a ? y L i,f p f ° rm fc yP ed int0 u when carriage return is struck after 
it. The form must b^ nn rmo iina< = « *»»-».«.. «*..-....... ic ^.-u- * 

nas syntactic errors (e.g., miscounted parentheses). The result 
of the evaluation is placed in the LDEBUG buffer on the next 
line, following the sign •->", which indicates the result of such 
an evaluation. The Lisp variable "*" is set to the result of 
each successive evaluation, as at raw Lisp top level; this may be 
used to reference the last printed result. " 

Random Lisp forms such as "(+ 2 3)" or "current-buffer" can 
be typed at LDEBUG buffers, and the resulting buffer contents 
will m effect be a dialogue of an interaction with Lisp. Such 
buffers are often dprintable for later perusal. The values of 
variables can be set by evaluating the normal Lisp seta form 
e.g., isetq var (+ foo 27)). As lines are placed into the "LDEBUG 
buffer by the LDEBUG facility, the window (if any) containing it 
scrolls, if necessary. a 
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Lisp values "printed" into the LDEBUG buffer are by default 
limited in length to ten and depth to six. The values of the 
option variables "ldebug-prinlength" and "ldebug-prinlevel" can 
be set to alter these defaults. The default input and output 
radices are both 8: these can be altered as the option variables 
"ldebug-ibase" and "ldebug-base" . As with ESC ESC, "#" 
represents elements deeper than the depth limit and "..." 
elements longer than the length limit. 

Most Emacs requests can be used in LDEBUG buffers; they are 
in Lisp Debug mode, which, is an extension of ordinary Lisp mode, 
with requests differing as detailed below. 

EMACS AND LISP DEBUG MODE 

The Idebug- (ESC X ldebug CR) extended request can be invoked 
at any time, in the usual way Emacs extended requests are 
invoked. It places Emacs in the LDEBUG buffer as described 
above, and also sets up a system of Lisp error handlers "under" a 
new invocation of the Emacs request loop. Should any Lisp error 
occur while these handlers exist, the LDEBUG buffer is entered, 
placed on display if not already on display, the terminal's bell 
is beeped, and the Lisp error message is entered in the LDEBUG 
buffer. You are then at a "second (or greater) level" of LDEBUG, 
similar to being at Multics command level when an error occurs. 
The level number is part of the message entered in the LDEBUG 
buffer. 

Recursive (level, greater than 1) LDEBUG buffers can be 
released (aborting all executing code between the LDEBUG level 
being released and the previous level) via the ESC G 
(Idebug-return-to-emacs-top-level) request, the analogue of the 
Multics release command. It beeps and types "$g" in the LDEBUG 
buffer. The value of the variable ldebug-level tells the current 
level of LDEBUG buffers. 

ESC P (for proceed) is the analogue of the Multics start 
command; more about its meaning for each different type of entry 
to an LDEBUG buffer is described below. In general, it restores 
the buffer and window from which the LDEBUG buffer entered. 
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ERROR TRAP ENTRI ES TO LDEBUG 

When an error trap entry to the LDEBUG buffer has occured, 
the Lisp stack can be traced via the ESC T (ldebug-trace-stack) 
request, and the value of variables can be inspected simply by 
typing their names (since they are Lisp forms) to the LDEBUG 
buffer. For this to work most effectively, at least one level of 
LDEBUG should be in the stack before the error is encountered. 

A value can be returned to the Lisp error handler by typing 
it on a line, and instead of ending the line with carriage return 
(which would evaluate and "print" the result), ending it with ESC 
P. Lisp error handlers often want a list of the value to replace 
some erroneous value. For instance, in the following dialogue, 
an LDEBUG trap was entered because of the unbound variable 
"stuff": the programmer returned the symbol "value-i-wanted" as 
the intended value of the unbound variable: 

(myfun huff stuff) 

Lisp breakpoint unbnd-vrbl at level 1 in buffer LDEBUG: 
lisp: undefined atomic symbol stuff 

( ' value-i-wanted) $p 

All correctable Lisp error breakpoints accept a retry value to be 
used to retry the failing operation; the undefined function 
breakpoint ("undf-fnctn") also accepts a list of a new value, in 
this case a function to be used instead. 

The B $p" is always printed by ESC P, to remind the user of 
the $p which is used in raw Multics MacLisp to restart breaks. 
ESC P can also be used alone on a line (i.e., no value to be 
returned preceding it) to restart a break and let Lisp's default 
action occur. 



ESC G can be used as usual to release a level of errors to 
the next lower LDEBUG level; A G (command-quit) does not release 
past LDEBUG levels. 
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CODE BREAKPOINTS 

Breakpoints can be set in interpreted extension code being 
debugged by typing ESC & in a Lisp Mode buffer with the cursor at 
the point in some function being debugged where you would like 
this break set. The LDEBUG mechanism creates this breakpoint by 
putting a call to a tracing function ("%%") in the code in the 
buffer, and evaluating the function definition it is looking at. 
This break code is left in the function to let you know that it 
is there: it includes a break number (they are assigned 
sequentially) to which this breakpoint can be referred by 
requests yet to be described.. 

You should be in at least one level of LDEBUG buffers before 
setting a break: thus, you should have said "ESC X ldebug CR" 
some time before setting breaks. 

Having set a break, you can run the code being debugged. 
When the breakpoint is entered, the LDEBUG buffer is entered at a 
new higher level.. A message of the form: 

Break 4 in function test fun 

is put in the buffer, and the LDEBUG buffer is put on display. 
As in all LDEBUG buffers, arbitrary forms can be evaluated 
(including inspecting variables), and ESC T can be used to trace 
the Lisp stack. Again, ESC G releases a level of LDEBUG buffers. 

ESC P is. used to restart code breakpoints as well._ A given 
breakpoint can be set for some number of proceeds (i.e., "3" 
means proceed, and proceed this breakpoint the next two times it 
is encountered automatically) by giving that number as a numeric 
argument to ESC P (i.e., ESC 3 ESC P) . A message indicating the 
number of proceeds is inserted in the LDEBUG buffer. ESC P 
should be used alone on a line (i.e., no retry value) when 
restarting code (or trace) breaks. 

When in a code break, ESC R (ldebug-reset-break) resets the 
current breakpoint, before restarting or releasing. The break 
code is removed from the function definition (visibly, if it is 
on display), and the function definition is reevaluated. ESC R 
with a numeric argument can be used to reset a break by number. 

In an LDEBUG buffer, ESC L (idebug-list-breaks) lists all 

i-V-^ !-_._..— _ —J ,. u...!, n A^n4-;i +. >m» •! t- niimK^»»*e; +- Ho funrf i nn in uhl rh 
tfle \riUWIl WUtie Ul.CoK^Wllll.bt l-ucil. uumuvii. Jj v.ii<- - wn.v. w * v.. ».. ....-—.. 

each break appears, the buffer that function appears in, and the 
status of each break. 
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The source for the current breakpoint can be shown by 
issuing the request ESC S (ldebug-show-bkpt-source) . It is 
placed in an available window (if in multiple window or 
pop-up-wmdow mode), and the cursor is moved to the break code. 
Use A XO to get back, or, in one-window mode, A ZB CR. 

During function breakpointing, to determine where the editor 
was (i.e., what was the current buffer, and where was the current 
point) at the time the breakpoint was encountered use ESC A S 
(ldebug-display-where-editor-was). it selects the appropriate 
buffer, moving the cursor to the point in it where the current 
point was when the breakpoint was taken. If the buffer is 
already on display in some window (or pop-up windows are being 
used), that window is selected, and A X0 returns you to the LDEBUG 
buffer for further probing or restarting. In one-window mode, 
the correct buffer is switched to, and A XB gets you back. If the 
current point is moved by you explicitly (i.e., via normal Emacs 
requests) while visiting the buffer where the breakpoint was 
taken, it has its new position when the breakpoint is restarted. 
This is analogous to setting a variable before restartinq with 
usual Multics debugging. 

Using two or three windows to contain the LDEBUG buffer, the 
breakpoint source (function being debugged), and the buffer the 
functions being debugged are working on, is highly effective. 

FUNCTION TRACING WITH LDEBUG 

The standard MacLisp trace package can be used while in 
Emacs; extensibility features of the former allow LDEBUG to take 
control of the trace output and breakpointing provided by it. 

All the facilities of the standard trace package can be 
used, by invoking trace from ESC ESC minibuffers. The trace 
package allows tracing of entries and exits to functions, 
arguments, and return values, and breakpoints when functions are 
entered. Some sample forms to trace the function testfun are 
given here: these are in Lisp syntax, and can be typed as such 
to LDEBUG mode. When typed to an ESC ESC minibuffer, the outer 

(trace testfun) 

Traces the input arguments and returns value of testfun 
each time it is invoked. 

(trace (testfun break (< x 3))) 

Traces input and returns value of testfun, enters a 
breakpoint when entered and x (x can be an argument to 
testfun) is less than 3. 
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(trace (testfun break t)) 

Same, but enters a breakpoint at every entry to 
testfun. 

(trace (testfun entry (a b) exit (c))) 

Traces, input arguments and returns value. Also prints 
out the values of a and b when testfun is entered and 
the value of c when it is exited. 



The general syntax of trace invocations is (brackets 
indicate- optional clauses r and angle brackets are syntactic 
variables) : 

(trace <fnname-or-clause-l> ... <fnname-or-clause-n>) 

where <fnname-or-clause> is either a function name to be traced 
for input arguments only and return value, or: 

(<fnname> [break <break-condition>J [entry (<entry-vals>) ] 

[exit (<exit-vals>)]) , 

When a function is traced within Emacs (it is not 
recommended to trace internal Lisp or Emacs primitives, and no 
part of the redisplay should be traced in this way), trace output 
for entry and exit tracings are placed (and scrolled) directly 
into the LDEBUG buffer if it is on display; if it is not on 
display, this output is put in the LDEBUG buffer, and locally 
displayed as it is produced. The line of dashes and asterisks of 
local displays is not produced, as it cannot be known when the 
end of trace output has been reached. Thus, traced functions 
invoked from the minibuffer may often leave the cursor in the 
minibuffer awaiting clearing of. the local display via linefeed or 
A L. 

Trace output generally looks like: 

(3 enter testfun (3 5 (a . b) ) /|/| (4 5)) 

The indentation level gives the depth in currently active traced 
functions. The "3" is the recursion depth of the given function 
(e.g., testfun) being traced. The "enter" is the type of trace 
(enter vs. exit), (3 5 (a . b)) is the list of arguments (in 
this case, three arguments). The /|/| sets off the entry values 
and exit values optionally selectable by the entry and exit 
keywords in the trace-invoking form. Exit traces look like: 

it x j- j — a- r . - _ i t \ 

\o ex it ceanuu x/j 
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If trace is used to set an entry breakpoint, the LDEBUG 
buffer is trapped to at the time the traced function is entered, 
in a way very much like a Lisp error break to LDEBUG. A message 
such as: 

Entry breakpoint to function testfun 

is printed into the LDEBUG buffer, and the terminal beeped. As 
with LDEBUG code breaks, ESC G releases, ESC P restarts, ESC R 
resets, and ESC A S shows where the editor was at the time the 
break was taken. When in entry breakpoints to interpreted 
functions, the arguments can be inspected by name. ESC T can 
trace the Lisp stack, but unless *rset t mode was in effect 
(setting up an LDEBUG level does this automatically), trace 
information may not be present. 

It is not necessary to have invoked ldebug before invoking 
trace in Emacs,* LDEBUG is invoked automatically if an attempt is 
made to use trace in Emacs. If some critical mechanism is being 
debugged and normal trace handling (i.e., breakpointing/tracing 
to user_i/o from Lisp, not the Emacs handling just described) is 
necessary, the variables trace-printer and trace-break-fun should 
be made unbound (e.g., ESC ESC makunbound 'trace-printer) before 
the first reference to trace in a given invocation of Emacs. 
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SECTION 5 
WRITING EMACS TERMINAL CONTROL MODULES (CTLS) 



Support of video (and printing) terminals in Emacs is 
accomplished via terminal-dependent modules known as CTLs. There 
are about two dozen supplied CTLs. Emacs attempts to locate an I 
appropriate CTL by using the regular search rules, based upon the I 
terminal type maintained by Multics, and optional Emacs control I 
arguments. The list_emacs_ctls command is provided to list all I 
the known terminal CTLS. " j 

To support a type of terminal not supported by a supplied 
CTL, you must write a new CTL. A CTL is written as a Lisp source 
program, named TTYTYPE.ctl.lisp, where TTYTYPE is the name of the I 
terminal type to be supported. If this terminal type is in your I 
site's Terminal Type File (TTF), the name chosen should appear 
the same as it appears in the TTF, except that the name of the 
CTL should be all lowercase (Emacs iowercases terminal types when 
looking for CTLs). 

CTLs are usually written by example from supplied CTLs. 
Personnel with no knowledge of Lisp at all have achieved this 
successfully. Once the CTL is written, it must be compiled 
before it can be used. Compilation is performed via the Lisp 
compiler, lcp. A typical command line to compile a CTL is: 

lcp super58.ctl ■ 

This produces an object segment, super58.ctl. * 



5-1 CJ52-01 



I Two control arguments for setting the terminal type are 
j recognized by Emacs when given as a command line argument. These 
| are: 

emacs -terminal_type STR or emacs -ttp STR 

where STR is your terminal type. The value of STR 

| can be any recognized editor terminal type. The CTL 

| is found via. the user's search rules. The terminal 

| type given, by STR is set only for the current 

| invocation of Emacsr in subsequent invocations, Emacs 

| checks your Multics process terminal type if you have 

I not respecified it with -ttp.. 



emacs -query 

Emacs queries the user for the terminal type without 
checking the Multics terminal type first. The answer 
you give may be any STR accepted by the -ttp option. 

Added names and links can be used to support many TTF 
terminal types via one CTL. When Emacs is given a terminal type 
(either from Multics Communication System or the -ttp control 

^yt-mmmn*- \ f r\y uKirVi iK /»ar>n^\+* f i rtA a PTT. 1 +» scire won if Trrvu want- 

to see the list emacs ctls list of known terminal CTLs. 



The most effective method of writing a new CTL is to take 
one that was written for a similar terminal and modify it. 
Almost all of the extant CTLs were written in this way. The 
sources are Lisp source segments, generally one or two printed 
pages long. Good starting points are: 

a vip720(Kctl.lisp, typical of terminals that do not have 
the ability to insert or delete lines or characters. 

» vip7800.ctl.lisp, typical of terminals that do have 
these abilities. The two facilities are independent, 
either one, both, or neither may be present, although 
use of terminals without insert/delete lines at less 
than 1200 baud may be found to be unacceptable. 



The interfaces (function definitions) in a CTL are 
standardized. They have the same names in all CTLs. The Emacs 
screen manager calls these interfaces anonymously after the 
appropriate CTL has been loaded. The interface DCTL-init is 
called at Emacs start-up time; it has the responsibility of 
setting various flags, and initializing the terminal. It should 
contain the statements: 
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(setq idel-lines-availablep t) 

if the terminal can insert/delete lines. 

(setq idel-lines~availablep nil) 
if it cannot. 

(setq idel-chars-availablep t) 

if the terminal can insert/delete/ characters. 

(setq idel-chars-availablep nil) 
if it cannot. 

(setq tty-no-cleolp t) 

if the terminal has no clear-to-end-of-line facility. 
Such terminals are generally unsatisfactory at speeds 
less than 2400 baud. 

(setq region-scrool-availablep t) 

if the terminal has region scrolling (see below). 

(setq screenheight N.) 

where N is the number of lines on the screen (note 
the dot after the N). 

(setq screenlinelen M. ) 

Where M is one less the number of characters in a 
line on this terminal. Again, note the dot. 

(setq tty-type 'TYPENAME) 

Where TYPENAME is a word like n suDer58" that 
identifies the terminal type. 

At the time DCTL-init is invoked, the variable ospeed is set 
to the speed of the communications line in characters per secon d 
(e.g., 1200 baud is 120 chars/sec). This can be used to perform 
padding calculations. This value is usually computed from the 
line speed maintained by the Multics Communication System. The 
-line speed control argument can be used to specify terminal 
speed for users logged in via the ARPANET. 

X ? a ?SJi tio !!' ?° u can " se t ? e "P a ge_length or -line_length | 
con^ro* arguments to override the terminal controller defaults I 
for page and line lengths. ** ■ 
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Also before DCTL-init is invoked, the variable 

given-tty-type is set to the name by which the CTL was loaded 

with the "ctl" suffix stripped. This variable can be used in 

DCTL-init (and elsewhere) to enable and use different features of 

a terminal, dependent on the name used to reference that terminal. 

To ensure that given-tty-type is different for various versions 

I of a terminal, give the additional varieties of the terminal as 

I added names on the CTL segment. For example, the names 

I vtlQQw.ctl, vtlOOws.ctl, and vtlOO.ctl are all associated with 

I the same CTL segment. This allows the VT100 CTL to distinguish 

between various screen widths and heights, by using the value of 

given-tty-type. The: "eq" predicate (i.e., (eg given-tty-type 

'dd4000)) can be used to check the value of this variable. The 

variable tty-type should be set by the CTL to a generic terminal 

type, e.g., vtlOO for all varieties of VT100, as opposed to the 

type given in given-tty-type. 

The following functions are available to the CTL writer: 

a Rtyo takes one argument, a number (fixnum), and outputs 
that number as ASCII data. For example, (Rtyo 141) 
outputs an "a", and (Rtyo 33) outputs an ESC. 

s Rprinc takes one argument, a character string, and 
outputs it. For example, (Rprinc n ]I") outputs a right 
bracket and an I .. 

Both of these functions buffer their output until the Emacs 
screen manager dumps this buffer. This is always done at the end 
of any redisplay at all, and after DCTL-init is called. 

The CTL writer must maintain the values of the special 
(global) variables X and Y relative to a zero origin screen 
position where the cursor was left. In return, you get to 
inspect these variables to do positioning optimization. 

The CTL writer must provide the following interfaces to be 
called by the Emacs screen manager: 

a. DCTL-init (no arguments). Must set the flags listed 
above, initialize the terminal (if necessary), clear 
the terminal screen, and leave the cursor at position 
(0, 0) (home). 



5-4 CJ52-01 



» DCTL-posit ion-cursor (two arguments, a new X position 
and a new y position). Move the terminal's cursor to 
the given position. Position 0, is defined as the 
upper left hand corner of the screen. This function 
must check the variables X and Y, and output no 
characters if the cursor is known to be already at the 
desired position. Otherwise, it must use the values of 
X and Y to determine what type of motion is necessary, 
output characters to move the cursor, and update X and 
Y to the input parameters (the delay of the buffered 
output is not an issue). 

Typically, DCTL-position-cursor determines which is the 
optimal movement based upon the relative Dositions of the cursor 
and the desired position. For terminals that have many forms of 
cursor movement, some combination of backspaces, linefeeds, and 
carriage returns may be adequate to effect some forms of cursor 
movement. Sometimes the sequences generated by the arrow buttons 
on the terminal may be used for relative positioning. Just about 
a C . ten ? inals . include some form of absolute positioning. The 
choice of optimal cursor positioning should be based upon which 
Sii i^SSS* ^V^eft characters to effect the desired move. I 
See hp2645.ctl.lisp for an example of a very well optimized 
cursor positioner. * 

One useful trick in the writing of DCTL-position-cursor is 
the use of recursion. See adds980.ctl.lisp for an example. If I 
you choose to use terminal tabs, then your DCTL-init must set I 
uxiem, anu you must take care not to clear them. No supplied CTLs " 
(other than the extremely special-case printing terminal 
controller) use tabs. 

» DCTL-di splay-char-string (one argument, a character 
string to be displayed). Must output this character 
string to the terminal at the current assumed cursor 
position. The string is guaranteed to contain no 
control or other nonprinting characters, and each 
character in it is guaranteed to take up only one print 
position. Be careful to update cursor position after 
printing the string; the lisp function stringlength may 
be used to ascertain the length/printing length of the 
string. 
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8 DCTL-kill-line (no arguments). Clear the line fromthe 
current assumed cursor position to the end of the line, 
and leave the cursor at that original assumed position. 
Most video terminals have a clear-to-end-of-line 
feature; it should be used here if available. Some 
terminals do not, so the flag tty-no-cleolp must be set 
to indicate this and DCTL-kill-line not defined. If 
this flag is set, the Emacs redisplay simulates 
clear-to-end-of-line by overwriting portions of lines 
with spaces. This technique is tedious but necessary. 

Hi DCTL-clear-rest-of-screen (no arguments) . Clear the 
screen from the current assumevj, cursor position -o -»*e 
end.. Leave- the cursor where it was supplied. Some 
terminals have a "clear whole screen" function, but not 
clear to end of screen. Currently, you can use the 
clear whole screen function. If your terminal does not 
even have a clear-whole-screen function, it is probably 
not worth using with Emacs , If you choose to use tabs 
in cursor positioning, be wary of clearing them via 
this function. 

Those are all the required functions. Some terminals 
require control sequences to change modes between normal Multics 
operation and operation within Emacs. (For example, a terminal 
might be switched between line-at-a-time transmission and 
character-at-a-time transmission.) Yet other terminals might use 
features during the operation of Emacs that should _ be 
disabled/reset when using Multics. (For example, the Digital 
Equipment Corporation VT100 uses "scroll" regions to simulate 
insert/delete lines. However, if a scroll region _ exists, it 
makes parts of the screen unusable when using Multics.) It is 
possible and quite common to switch between Multics and Emacs by 
using the ATTN key and the program_interrupt command. In such 
cases, the terminal is in the wrong mode at various times. If 
the terminal for which you are writing a CTL exhibits _ this 
behavior, you should add the following statements to DCTL-init: 

(setq DCTL-prologue-availablep t) 

to specify that certain functions must be performed 
each time Emacs is entered from Multics. 

(setq DCTL-epilogue-availablep t) 

to specify that certain functions must be performed 
each time Multics is entered from Emacs. 
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In addition, you must then supply the following two functions: 

a DCTL-prologue (no arguments). Perform any operations 
that are required when Emacs is entered from Multics. 
This function is invoked immediately after DCTL-init is 
called and after Emacs is reentered after a QUIT via 
either the Multics program_interrupt or start commands. 

a DCTL-epilogue (no arguments). Perform any operations 
that are required when Multics is to be entered from 
Emacs. This function is invoked immediately before 
Emacs is exited when the A X A C (quit-the-editor) request 
is invoked, and immediately before Emacs is suspended 
when the A Z A Z (quit) request is invoked or the ATTN key 
is hit on the terminal. ' 

If you have stated that insert/delete lines is available 
via setting the flag idel-lines-availablep to t, you must supply 
the following two functions. If you set this flag to nil, you 
need not write these functions: y 

8 DCTL-insert-lines (one argument, a number of lines to 
be inserted). Open up the given number of lines on the 
screen. There are that many blank lines (created by 
DCTL-delete-lmes) at the bottom of the screen at the 
time this function is invoked. The cursor is at 
position of some line at the time DCTL-insert-lines 
is invoked. It must push the contents of that line 
down the supplied number of lines, leaving the cursor 
in cne same place, and the line the cursor is on and 
the n-1 succeeding lines blank. 

b DCTL-delete-lines (one argument, a number of lines to be 
deleted). Delete from the screen the supplied number 
of lines, starting with the line the cursor is on and 
proceeding downward. The cursor is to be left in the 
same place it was given. That many blank lines are 
assumed to be pulled up on the bottom of the screen. 

► k 4. " th f. fla 9 idel-chars-availablep is set to t, indicating 
that insertion and deletion of characters is available, the 
following two functions must be supplied: 

8 DCTL-insert-char-string (one argument, a character 
string to be inserted at the current assumed cursor 
position). Insert the character string supplied at the 
current cursor position. Push to the right all 
characters at, and to the right of, the current cursor 
position. There are only blanks on the screen in the 
region being pushed off. Leave the cursor (and so 
updat) after the last character of the inserted string. 
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a DCTL-delete-chars (one argument, the number of 
characters to be deleted) . Physically delete from the 
screen the supplied number of characters, starting with 
the character at the cursor and on the right. Move all 
characters to the right of these characters that many 
positions to the left. That many blanks are assumed to 
be moved in from the right edge. Leave the cursor 
where it was supplied. 

Some terminals, such as the DEC VT1Q0 and the Human Designed 
Systems Concept 100, offer a feature called region-scrolling, 
which allows groups of lines to be moved up or down at once 
without the two-step operation of delete-lines followed by 
insert-lines. The Emacs redisplay can take advantage of this 
feature? the result is scrolling without the "jumping 
minibuf fers" and pulling and pushing associated with window 
management via insert/delete lines. If your terminal has region 
scrolling, do not define DCTL-insert-lines and DCTL-delete-lines 
for your terminal. Instead, setq the special variable 
region-scroll-availablep to t at DCTL-init time. The following 
two functions must then be defined: 

a (defun DCTL-scroll-up-region (amount bottom)...) 

This operation will be invoked with the cursor at the beginning 
of some line of the screen. It defines an operation affecting a 
region that includes the current line down to, but not including, 
the line designated (by number, in the second argument) as the 
<bottom> (where the first line on the screen is 0). This region 
is scrolled up by <amount>, where amount is the number of lines 
given as the first argument. The cursor is left where it is, at 
the beginning of the newly scrolled-up current line. So, in 
efect, where <size> is the size of the region (in lines), the 
lower <size minus amount> lines of the region are moved up to 
become the topmost <size minus amount> lines of the region. The 
last <amount> lines of the region are left blank, and the 
contents of what were the first <amount> lines depart 
irretrievably from the screen. In the following example, assume 
C represents the cursor and call: 

(DCTL-scroll-up-region 2 7) 

Before After 

Foo Foo 

Bar Bar 

CQuux CLuux 
Truux Buux 

r. iiiiv Paaf C 

BUUX 

Bears 
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Cubes 
Bmacs 



Cubes 

Emacs 



The second function is: 

a (defun DCTL-scroll-down-region (amount size)...) 

I^I^r! 10 "/;! 1 be invoked with the cursor at the beginning 
rf„?SJ\i i ; e . of , t 5 e sc 5 een - J t defines an Operation affecting a 
region that includes the current line down to, but not including, 
line number <bottom>, where the first line on the screen is 
The size of this region, in lines, is <size> (the second 
argument). This region is scrolled down by <amount> (the first 
argument) lines, and the cursor left where it is at the beginning 
of the. current line of the screen. So, in effect, thl uppe? 
<size minus amount> lines of the region are moved down to be the 
bottommost <size minus amount> lines of the region. The first 
<amount> lines are left blank, and the contents of what were the 
last <amount> lines departs irretrievably from the screen. 

Again, in the following example assume C 
cursor and call: 

(DCTL-scroll-down-region 2 7) 
Before After 



represents the 



Foo 
Bar 
CQuux 
Truux 
Luux 
Buux 
Bears 
Cubes 
Emacs 



Foo 

Bar 



Quux 

Truux 

Luux 

Cubes 

Emacs 



1-rvino it 9 S-* C ? L u ? uall y involves editing an existing one, 
»Z ?S X*. modl fy i "9 xt ' and ' iterating until it is solid! You 
use the -ttp control argument many times to switch back and forth 
between printing terminal mode and the new CTL when logged in 
from, the terminal on which the CTL is being developed. For 
terminals with insert/delete features, it may be convenient to 
debug the CTL first without these features (claim they are no? 

add them. later. Similarly, you are 
DCTL-position-cursor once you have 
the convenience of editing the CTL 



there in the DCTL-init), and 
encouraged to write a better 
one that works at all, for 



with Emacs substantially reduces the effort of 



improving it. 
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For some terminals, padding may be necessary for some 
operations at some or all line speeds. If terminal behavior 
appears random, or garbage is left on the screen after a A L or 
A K, this may be the problem. Check the manual for your terminal 
about padding requirements. It may be convenient to define a 
function called DCTL-pad, which takes a number of microseconds or 
milliseconds as an argument, and issues enough pad characters to 
perform this padding. (Rtyo 0) or (Rtyo 177) are common, but 
check your terminal manual for what your terminal expects; (Rtyo 
0) generally works. The variable ospeed gives the line speed in 
characters, per second, for use in such calculations. Getting the 
padding right may invoLve quite a bit of tinkering on some 

!.___.: „.» i _ . ««» nr>»TYAn mo^Kn^ in f»aeae uhor» naflidinfl IS felt to b© 

a problem is to specify a very large amount of padding (e.g., a 
second) and cut it down until it works. See dd4000.ctl.lisp for 
an example of. terminal padding. 

The Lisp special forms cond and do are used heavily in CTLs. 
Since Emacs environment macros (do-forever, if, etc) should not 
be used in CTLs, the native Lisp forms are necessary. Here are 
the descriptions of cond and do: 

(cond (( = this that) (thingl) (thing2) ) 
((> a b) (second) (third) 27) 
((< c 15) (other)) 
(t (best 5) (chance))) 



means: 



"If this equals that, call thingl of no arguments, then call 
thing2 of no arguments, and return as the value of the cond 
the value returned by thing2. Otherwise, if a is greater 
than b, call "second" with no arguments, then call "third", 
and return 27 as a value. Yet otherwise, if c is less than 
15 (all numbers octal), return the value obtained by 
applying "other" to no arguments. If none of the above are 
true, call "best" with an argument of 5, and then return the 
value obtained by calling "chance" with no arguments." 



5-10 CJ52-01 



The cond special form is much like PL/I ' s 
if ('.... ) then do; 



end; 

else if ( .... ) then do; 



end; 

else if ( .... ) then do; 



end; 
else do; 



end; 

The format of Lisp "do" used in CTLs to iterate is: 

(do VARIABLE INITIAL-VALUE REPEAT-VALUE TEST forml form2 
form3.. ) 

It is equivalent to PL/I's: 

do VARIABLE = INITIAL-VALUE 
repeat REPEAT-VALUE 
while ( A TEST) ; 

forml ;form2; ... 
end; 

which, itself, is equivalent to: 

VARIABLE = INITIAL- VALUE; 
1: if TEST then go to e; 

forml ;form2; ... 

VARIABLE = REPEAT-VALUE; 

go to 1; 
e: 

The variable VARIABLE is locally defined inside the do. It may 
be used in the forms inside the do, in the "end test" TEST, and 
in the repeat value REPEAT- VALUE . 



5-11 CJ52-01 



APPENDIX A 
THE BACKQUOTE FACILITY 



The backguote facility defines two characters with special 
syntax to the Lisp reader: backquote C— ASCII code 140) and 
comma (, —ASCII code 54). These two "macro characters" can be 
used together to abbreviate large compositions of functions like 
cons, list, list*, and append. It is typically used to specify 
templates for building code or other list structure and often 
finds application in the construction of Lisp macros. 

If you are in Emacs, backquote is automatically defined 
correctly for you. ESC-ESC, LISP mode, and LDEBUG mode all 
handle it properly. If you write extension code that uses 
%mclude e-macros. incl.lisp (as all extension code should), 
backquote is defined properly for you as well. If you are 
writing Lisp code other than Emacs extensions, your proqram 
should include the form (%include backquote) before the first'use 
of backquote. 

Backquote has a syntax similar to that of quote (' — ascii 
47). A backquote is followed by a single expression. If the 
expression does not contain any use of the comma macro character, 
then the form will simply be quoted. For example: 

Ma b c) => (quote (a b c)) ■> *(a b c) 

The comma macro character can only be used within a form 
following a backquote. Comma also has a syntax like that of 
quote. The comma is followed by a form, and that form is 
evaluated even though it is inside the backquote. For example: 

(cons a (quote (b c) ) ) 
(cons a '(be)) 

(list* (quote a) b (quote (c))) 
(list* 'a b ' (c)) 
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M,a b c) 


=> 




=> 


Ma ,b c) 


=> 




=> 



Ma b ,c) => (list (quote a) (quote b) c) 
=> (list 'a 'b c) 

Ma . ,rest) => (cons (quote a) rest) 
=> (cons 'a rest) 

Thus, to write the common macro "push" using backquote, proceed 
from the standard definition: 

(defun push macro (form) 

(list 'setq (caddr form) (List 'cons (cadr f orm) (caddr form 

to: 

(defun push macro (form) 

Msetq , (caddr form) (cons , (cadr form) , (caddr form)))) 

Note how the code to build the macro's output code begins to look 
more like the output code itself. In fact, using let, you can go 
all the way to: 

(defun push macro (form) 

(let ((datum (cadr form)) 
(list (caddr form))) 
Msetq ,list (cons , datum ,list)))) 

and produce very legible code. 

Backquote expands into forms that call cons, list, list*, or 
whatever other functions it deems appropriate for the task of 
constructing a form that looks like the one following the 
backquote, but with the values of the forms following the commas 
substituted in. 

If a comma inside a backquote form is followed by an at 
sign (8— ASCII code 100), then the form following the ",@" 
should return a list. Backquote arranges that the elements of 
that list will be substituted into the resulting list structure. 
Frequently this involves generating a call to the append 
function. For example: 

M,@a be) »> (append a (quote (b c))) 
=> (append a ' (b c) ) 

x (a ,@b c) ■> (cons (quote a) (append b (quote (c)))) 
=> (cons 'a (append b '(c))) 

\0. JJ , CS. J —' \ J. i o v. ^^^ww— — i 1-3 1 -/ -/ 

=> (list* 'a 'b c) 
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Similar to following the comma by an at sign is following 
the comma by a dot (.--ASCII code 56). The dot is a declaration 
to backquote telling it that the list returned by the form 
following the " , . " is expendable. This allows backquote to 
produce code that calls functions like nconc that rplac the list. 

Backquote examines the forms following the commas to see if 
it can simplify the resulting code. For example: 

Ma b . , (cons x y)} => (list* (quote a) (quote b) x y) 

=> (list* *a 'b x y) 

Ma 3 ,b c ,17) => (list* (quote a) 3 b (quote (c 17))) 

=> (list* 'a 3 b ' (c 17)) 

Ma ,@b ,<3nil) => (cons (quote a) b) 

=> (cons 'a b) 

Ma ,.b ,@(nconc c d)) => (cons (quote a) (nconc bed)) 

■> (cons 'a (nconc bed)) 

These examples should convince you not to depend on what the 
code that backquote expands into will look like. Backquote' s 
contract is specified not in terms of the code that it expands 
into but rather in terms of what that code produces when 
evaluated. A simple backquote might expand (,§a ,§ni.l) into 
(append a 'nil), but this cannot be used as a reliable way to 
copy a list since a sophisticated backauote (like this on e ^ ^n 
optimize the copying away. 

It is sometimes useful to nest one use of backquote within 
another. This might happen when writing some code that will cons 
up some more code that will in turn cons up yet more code. The 
usual example is in writing macro-defining macros. When this 
becomes necessary it is sometimes difficult to determine exactly 
how to use comma to cause evaluation to happen at the correct 
times. The following example exhibits all the useful 
combinations: 

"(a ,b ,,c ,\d) 

(j.ist xist- -a be tust 'quote (list d) ) ) 



A- 3 - CJ52-01 



When evaluated once, this yields: 

(list* 'a b. <c-at-time-l> ' (<d-at-time-l>l ) 
Which when evaluated yields: 

(a <b-at-time-2> «c-at-time-l>-at-time-2> <d-at-time-I>) 

Thus nn means never evaluate, "," means evaluate only the second 
time, ",,"• means, evaluate both times, and ",', " means evaluate 
only the first time- 
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APPENDIX B 
QUICK REFERENCE 



The following functions, special forms, predicates, and 
global variables mentioned in this manual have been grouped below 
according to the uses they serve in extensions. Following those 
groupings is an alphabetized list that includes a brief 
description of each function, special form, predicate and global 
variable listed. The categories include: 

Buffers 

Calculations 

Catenation 

Character/Numeric Conversion 

Charscan Table/Characters 

Comments 

Comparison 

CTL 

Debugging 

Defining/Calling a Command/Function/Property 

Displays 

Error Handling 

Execution and Conditional Evaluation 

Files 

Killing 

List Processing/Cons 

Marks 

Mini buffers/Prompts 

Modes 

Modified Flag 

Multics Command Execution 

Point Position 

Searching 

Variables 

Whitespace 

Windows 

Miscellaneous 
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Buffers 

| buffer-creation-hook 
| buffer-destruction-hook 
| buffer-entrance-hook 
| buffer-exit-hook 
buffer- kill 
buffer-minor-modes 
buffer-modi fied-f lag 
buff er-on-di splay- in- window 
cur r en t-buf fer 
curren t-buf f e r-mode 
destroy-buf f er-contents 
di splay-buff er-as-printout 
don t-not ice-modi f ied-buf fer 
empty-bu£fer-p 
establish-local-var 
find-buffer- in-window 
find-file-subr 
go-to-or-create-buf fer 
previous-buffer 
read-only-f lag 
save-excursion-buf fer 

select-buffer-window 
set-buffer-self-destruct 



Calculations 



// 

Catenation 



apply-catenate 
catenate 



Character /Number Conversion 

*nopoint 

ascii 

base 

Ctol 

decimal-rep 

ibase 

ItoC 
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Character Table/Characters 

charscan-table 

char set -member 

explode 

explodec 

get-char 

lef thand-char 

process-char 

search-back-first-char set-line 

search-back-first-not-charset-line 

search-char set-backward 

search-charset-forward 

search- for-f irst-charset-line 

search-for-f irst-not-charset-line 

search-not-charset-backward 

search-not-char set- forward 



Comments 

comment-column 
comment-prefix 

Comparison 
< 



a 1 nKa 1 acctn 

» — £»**** ^%i •?£?£* 

eq 

f ixp 

samepnamep 



CTL 



DCTL-clear-rest-of -screen 

DCTL-delete-chars 

DCTL-delete-lines 

DCTL-di splay-char-string 

DCTL-epilogue 

DCTL-init 

DCTL- insert-char-string 

DCTL-insert-lines 

DCTL- kill- line 

DCTL-posit ion-cursor 

DCTL-prologue 

DCTL-sc roll-down-region 

DCTL-scroll-up-region 

Rprinc 

Rtyo 
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Debugging 



debug-e 
ldebug-mode-hook 



Defining/Calling a Command/Function /Property 

defcom 

defprop 

defun 

funcalL 

get 

process-char 

putprop 

set-key 

set-permanent-key 



Displays 

display-as-printout 

display-buffer-as-print out 

display-com-error 

di splay-com-er ror-noabort 

display-error 

display-er ror-noabort 

display-error-remark 

end-local-di splays 

full-redisplay 

in it-local-displays 

local-display-current-line 

local-display-generator 

local-display-generator-nnl 

redisplay 

redi splay-cur rent-window-relative 

view-region^as- lines 



Error Handling 



add error code 


command- 


•quit 


display- 


•corn-error 


display- 


■error 


display- 


•error-noabort 


display- 


-error-remark 


error-table 


error table 


nmt-srf 





■ 

I report-error 

| report-error-noabort 

ring-tty-bell 
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trace 
unwind-protect 

Execution and Conditional Evaluation 

and 

cond 

dispatch-on-current-char 

dispatch-on-lefthand-char 

do 

do-forever 

do-times 

eval 

funcall 

go 

if 

if-at 

if-back-at 

mapc 

or 

prog 

progl 

prog2 

progn 

return 

save-excursion 

save-excurs ion-buffer 

save-excursion-on-error 

stop-doing 

unwind-protect 

without-modifying 

without-saving 



Files 



f ind-f ile-subr 
f pathname 
read-in-f ile 
write-out-f ile 
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Killing 



buffer-destruction-hook 
buffer-kill 

delete- white- sides 
delete-window 

des troy-buffer-con tents 

killsave-string 

kill-pop 

kill-ring-top 

rotate-kill-ring 

set-buffer-self-destruct 



2 / 83 B-5.1 CJ52-01A 



w i pe-po i n t-mar k 
without-saving 



List Processing/Cons 

append 

apply-catenate 

car 

cdr 

cons 

explode 

explodec 

list 

list* 

memq 

nconc 

nreverse 

reverse 

replaca 

replacd 



Marks 



der-wahrer-mark 

go-to-raark 

mark-at-current-point-p 

mark-on-current-line-p 

mark-reached 

mark-same-line-p 

point-mar k-to-st ring 

point>markp 

release-mark 

set-mark 

wipe-point-mark 

with-mark 



Mini buffers/Prompts 

| last-minibuf fer-response 
| minibuf fer-response 

minibuf fer-clear 

minibuf fer-pr in t 

minibuf fer-pr in t-noclear 

yesp 



Modes 



aim-mode-hook 
assert-minor-mode 
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buf f er-mi nor -modes 

current-buffer-mode 

fill-mode-delimiters 

fortran-mode-hook 

Idebug-mode-hook 

lisp-mode-hook 

ma i 1-mode-hook 

negate-minor-mode 

pll-mode-hook 

rma i 1-mode-hook 

text-mode-hook 



Modified Flag 



buffer-modi f ied-f lag 

don t-not ice-modi f ied-buf fer 

read-only-flag 

without-modifying 



Multics Command Execution 



comout-get-output 
e cline 



Point Position 

at 

at-beginning-of-buf fer 
at-end-of-buf f er 
at-white-char 
back-at 
.bolp 
cur-hpos 
curchar 
eolp 

f irstlinep 
go-to-hpos 
go-to-mark 
if-at 

if -back-at 
lastlinep 
looking-at 

mark-at-current-point-p 
next-line 

point-mark-to-string 
point>markp 
prev-line 
save-excursion 
save-excursion-on-error 
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Searching 



charscan-table 

forward- search 

get-search-string 

regexp-search 

reverse-regexp-search 

search-back-first-char set-line 

sear ch-back-f irst-not-char set-line 

search-charset-backward 

search-charset-forward 

search-failure-annunciator 

search-for-first-char set-line 

search-for-first-not-charset-line 

search-not-charset-backward 

search-no t-char set-forward 



Variables 



defvar 

establish-local-var 

let 

register-local-variable 

setg. 



WhitesDace 



at-white-char 

dele te-white-s ides 

format-to-col 

line-is-blank 

skip-back- to-white space 

skip-back-whitespace 

skip-back-whitespace-in-line 

skip-over-whitespace 

skip-over-whitespace-in-line 

skip-to-whitespace 

tab-equivalent 

whitespace-to-hpos 

Windows 

buff er-on-di splay- in-window 
delete-window 

find-buffer- in- window 
nuwindows 

yaA i ct-i1 ai;-riirront - -ui ndou-rpl at i Vg 

select-buffer-find- window 
select-buffer-window 
select-window 
selected- window 
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window-adjust-lower 
window-ad just-upper 
window- info 



Miscellaneous 

close-line-hook 

env-dir 

ESC 

fill-mode-delimiters 

insert-string 

maknam 

nil 

NL 

not 

null 

null-stringp 

print 

process-dir 

read- front-string 

ring-tty-bell 

stringp 

symbolp 

t 

yesp 

Each item described below also has a note that indicates 
what type of item it is. The item types ares 

Native Lisp function, variable, predicate, or special form 

Emacs environment function, variable, etc. 

CTL functions, to be defined by CTL writer, called by 

Emacs Redisplay, and not called by extension code under 

any circumstances. 



* Lisp function 

takes any number of arguments, which are expected to be 
fixnums (integer numbers), and returns their product. 

*nopoint Lisp global variable 

when bound to anything but nil, causes decimal numbers to be 
converted to their printed representation without a trailing 
decimal point. 

+ Lisp function 

adds any number of fixnum arguments. 
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Lisp function 
subtracts all of its (fixnum) arguments 
its. first argument. With two arguments, 
the difference. 



but the first from 
it simply computes 



// Lisp function , 

divides its first (fixnum) argument successively by each of 
Its succeeding arguments. Answer is a whole number 
(fixnum). With two arguments, it is a simple integer 
quotient. 



*•*..«£> tr- ~ 

o£ two arguments, 
than second. 



fixnums. Returns truth if first is less 



Lisp predicate 
of two arguments, fixnums. 
same fixnum. 

Lisp predicate 
of two arguments, fixnums. 
greater than the second. 



Returns truth if they are the 



Returns truth if the first is 



i add-error-code Entaes function # 

| of two arguments, error-code and error-string, adds an entry 

| to the Emacs Error Table. 

aim-mode-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering ALM mode in a buffer. Used to customize key 
bindings, etc. 

alphalessp Lisp predicate , 

of two arguments, can be symbols or strings. Returns truth 
if the printname (or string value) of the first collates 
alphabetically in the ASCII collating sequence before the 
second. 

and Lisp special form 

evaluates all of its subforms in order until one of them 
evaluates to nil, or they are all evaluated. The value 
returned by the last one evaluated is returned. 

append Lisp function . 

takes any number of lists as arguments, including empty 
lists. Returns a list with all the elements of the lists 
provided as elements, in order. 



apply-catenate Emacs function 

takes a list of any number of strings 
returns a string that is the catenation of 
values or printnames. 



or symbols, and 

all their string 
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ascii Lisp function 

returns a single-character symbol whose printname is the 
argument! ""^ ^ nUmeriC Value W * s ^iven as an 

assert-minor-mode Emacs function 

be °a e S vmb^ en ^c a S Sert ! tha 5 this minor mode (expected to 
Une^n Sy ?L 0l curren^ b bu?fer: ned ^ "•**«» in the mode 

at Emacs predicate 

of one argument, a single-character string or symbol 
Returns truth if the character to the right of point in the 
current buffer is this character. 

at-beginning-of-buffer Emacs predicate 

ir?h2 S vi«" th - if fc 5 e 5 u " ent P° int ^ the current buffer is 
at the beginning of the buffer. 

at-end-of-buffer Emacs predicate 

aT^en^of iJ.'&IEf" P ° int ln the CU " ent bu »« " 

at-white-char Emacs predicate s 

returns truth if the character to the right of the current 
point m the current buffer is a whitespale character? 

back-at Emacs predicate 

of one argument, a single-character string or symbol 
f^™f J«th if the character to the LEFT of point in it 
uuitenu ouner is tnis character. " ' """ 

base Lisp global variable 

Ease^n* ^Mrl ^k" 9 ° f the variable controls the numeric 
representation? ""**" m C ° nVerted t0 tbeir P'i»fd 

bolp Emacs predicate 

ir?£I! S h^"n h - if ^ c ^ rent P°int in the current buffer is 
at the beginning of a line. 

buffer-creation-hook Emacs global variable ■ 

ih«?°«« k° n ?r2 U ' itS bindin 9 is assumed to be a symbol 
that can be called as a function when a buffer is created? } 

buffer-destruction-hook Emacs global variable • 

Jh»?°JSn k° n ?T"2 ilf itS bindi ng is assumed to be a symbol 
that can be called as a function when a buffer is destroyed? | 

buffer-entrance-hook Emacs global variable ■ 

tL b ° U ?fn t0 K n ° n ;?4' itS bindin 9 is assumed to be a symbol 
selected? &S * function when « new buffer is j 
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I buffer-exit-hook Emacs global variable 

I if bound to non-nil, its binding is assumed to be a symbol 

| that can be called as a function when a, buffer is left. 

buffer-kill Emacs function . n — ^^.e 

of one argument, the symbol representing a buffer. Destroys 

that buffer. 

buffer-minor-modes Emacs per-buffer variable 

the list of symbols that have been asserted and not negated 
as the current minor modes in the current buffer. 

buffer-modified-flag Emacs per-buffer variable ^r..,, 

value is non-nil if the current buffer has been modified 
since last read in or written out. Do not set this flag by 
yourself; let Emacs manage it. 

buffer-on-display-in-window Emacs predicate , 

as a predicate, returns truth if the buffer whose symbol is 
"provided as an argument is currently on display in any 
window. 

buffer-on-display-in-window Emacs function _ 

r *.;„« «i-,,T-ne +-V.A window number in which tne ourier 



da a j-uiiv-uiuu, 



provided is on display (or nil if none) 

car Lisp function , . , 

returns the "car" of the argument, which is expected to be a 
cons. Note that for conses which are parts of lists, car 
may be viewed as returning the first element of the list. 

catenate Lisp function 4.,„.„« 

qiven any number of strings or symbols as arguments, returns 
a string that is the catenation of their string-values or 
printnames. 

cdr Lisp function , , 

returns the "cdr" of the argument, which is expected to be a 
cons. Note that for conses that are parts of lists, cdr may 
be viewed as returning a list of all the elements beyond the 
first element. 

charscan-table Emacs function 

takes a character-string argument, and creates a charscan 
table that can be used to search a string for those 
characters. 

charset-member Emacs function „„„u,o 

the first argument is a single cnaracter string, l sjm-o*, 
or fixnum that is the ASCII value of a charater, and the 
second argument is a charscan table. Returns truth if the 
character is a member of that charscan table. 
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close-line-hook Emacs global variable | 

if bound to non-nil, its binding is assumed to be a symbol | 

that can be called as a function when the user moves to | 

another line. | 

command-quit Emacs function 

aborts the execution of the current extension function, 
beeping, and returning to the Emacs character-listening 
loop. 

comment-column Emacs per-buffer variable 

the zero-based comment column in the current buffer. 

comment-prefix Emacs per-buffer variable 

the string to be inserted at the start of comments in this 
buffer, and searched for to find the start of already 
existent comments. 

comout-get-output Emacs function 

catenates all of its arguments into a Multics command line, 
and replaces the contents of the current buffer by the 
Multics output produced by executing that Multics command 
line. 

cond Emacs special form 

performs successive tests of conditions and conditionally 
executes forms. Specifically, evaluates the first subform 
of all of its own subforms, until one returns non-nil, and 
executes all the remaining subforms of that subform (of 
cond). returning the value of the last subform, of any kind f 
evaluated. See the writeup/examples. 

cons Lisp function 

constructs a new cons, whose car and cdr are the two 
arguments given. 

Ctol Lisp function 

obtains the numeric ASCII value of the character that is the 
printname (if a symbol, or value if a string) of its 
argument. 

cur-hpos Emacs function 

the zero-based current horizontal position of point on the 
current line in the current buffer. Note that this is 
horizontal position on an infinite-width line-printer or 
printing terminal, not on the screen. Tabs count, 
backspaces count, etc. 

curchar Emacs function 

returns the single-character symbol whose - printname is the 
character to the right of point in the current buffer. 
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current-buffer Emacs per-buffer variable 

the symbol representing the current buffer, 

current-buffer-mode Emacs per-buffer variable 

the symbol representing the major mode in the current 
buffer. 

DCTL-clear-rest-of-screen CTL function 

clear to the end of the screen from the cursor. 

DCTL-delete-chars* CTL. function 

delete n (argument) characters at the cursor, shifting the 
rest of the line over to the left. 

DCTL-delete-lines CTL function 

delete n (argument) lines from the screen at the cursor, 
moving the rest of the lines on the screen up. 

DCTL-display-char-string CTL function 

print the character string supplied as an argument at the 
cursor, moving the cursor to the end. 

DCTL-epilogue CTL function 

take appropriate actions to "reset" the terminal from Emacs 
mode to normal Multics mode. 

DCTL-init CTL function 

set up the CTL to operate and then clear the screen. 

DCTL-insert-char-string CTL function 

insert the character-string argument at the cursor, pushing 
the rest of the line over to the right. 

DCTL-insert-lines CTL function 

open up n (argument) blank lines at the cursor pushing the 
rest of the lines down, the n lowest off the screen. 

DCTL-kill-line CTL function 

clear from the cursor to the end of the line. 

DCTL-position-cursor CTL function 

takes x, y as arguments. Move the cursor (if not already 
there) to that position; x and y are zero based. 

DCTL-prologue CTL function 

ready the CTL for Emacs usage as opposed to Multics normal 

mode . 

nrniT _»---! 1 -Jnijn-roni An fTT. function 

scroll a region at the cursor down. 

DCTL-scroll-up-region CTL function 

scroll a region at the cursor up. 
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debug-e Emacs function 

sets error traps in Emacs so that extension code hues 
breakpoint in Lisp. ' 

decimal-rep Emacs function 

converts its (numeric) argument to a string that is its 
decimal representation. 

defcom Emacs special form 
defines a command. 

defprop Lisp special form 

puts a property on a symbol. Like putprop, but is a special 
£orm and does not evaluate any of its arguments. 

defun Lisp special form 
defines a function. 

defvar Emacs special form 

declares a special variable (first argument, not evaluated) 
and assigns a value if the variable has not been set when 
the program is loaded (second argument, evaluated). 

delete-white-sides Emacs function 

removes all whitespace characters on either side of point in 
the current buffer. 

delete-window Emacs function 

destroys the window whose window number is given. 

der-wahrer-mark Emacs per-buffer variable 

the true mark," i.e., the user-visible ( A @) mark in the 
current buffer. 

destroy-buffer-contents Emacs function 

destroys the contents of the current buffer. 

dispatch-on-current-char Emacs special form 

executes forms conditionally based upon the value of the 
character to the right of point in the current buffer. 

dispatch-on-lefthand-char Emacs special form 

executes forms conditionally based upon the value of the 
character to the right of point in the current buffer. 

display-as-printout Emacs special form 

displays as local display all of the text placed in the 
current buffer (which will be created by this form) by the 
forms contained in it. 

display-buffer-as-printout Emacs function 

displays the current buffer as local display. 
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display-com-error Emacs function 

takes a Multics error code argument and strings that are 
catenated to produce an error message in the minibuffer 
(including the converted Multics error code), aborts the 
current extension code execution, and beeps. 

display-com-error-noabort Emacs function 

like display-com-error, but does not abort. 

display-error Emacs function 

catenates its string arguments to produce an error message 
in the minibuffer. aborts the current extension code 
execution r and beeps. 

display-error-noabort Emacs function 

like display-error, but does not abort. 

display-error-remark Emacs function 

like display-error-noabort, but this output is suppressed 
during keyboard macro execution. 

do Lisp special form- 
complex native Lisp form for iterated execution. 

do-forever Emacs special form 

executes all of the forms contained within it until they 
return or abort of their own accord. 

do-times Emacs special form 

first form is evaluated to obtain a number; the rest of the 
forms are executed that many times. 

dont-not ice-modi f ied-buf f er Emacs function 

argument is a buffer-symbol. If called, that buffer's being 

modified does not prevent the user from exiting Emacs 
without being queried. 

e_cline_ Emacs function 

executes a Multics command line (the supplied string) 
without any arrangements for I/O, etc. 

empty-buff er-p Emacs predicate 

returns truth if the buffer-symbol argument represents an 
empty buffer. 

end-local-displays Emacs function 

indicates that a local display has produced all it is going 
to, and the next charater typed by the user should erase the 
local display. 

env-dir Emacs global variable 

the directory in which the Emacs subsystem is located. 
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eolp Emacs predicate 

returns truth if the current point in the current buffer is 
at the end of a line. 

eg Lisp predicate 

returns truth if the same object is given as both arguments. 

error-table Emacs function . 

of two arguments, segment and offset, gets a standard I 
Multics error code. j 

error__table_ Emacs function 

produces a Multics error code given an error table entry 
point name as a string or symbol. 

ESC Emacs global variable 

a single-character symbol whose name is the ESC character. 

establish-local-var Emacs function 

declares a buffer local variable and establishes a value. 

eval Lisp function 

evaluates a Lisp form. 

explode Lisp function 

creates a list of characters (single-character symbols) that 
is the standard Lisp printed representation of its argument. 

explodec Lisp function 

like explode, but does not escape Lisp special characters or 
quote strings. 

fill-mode-delimiters Emacs global variable 

the list of characters that cause fill mode to fill. 

f ind-buffer-in-window Emacs function 

takes a buffer-symbol argument, and either selects a window 
containing that buffer, or first puts it somewhere other 
than the current window (on an LRU basis) and then selects 
that window. 

f ind-f ile-subr Emacs function 

takes an argument like those acceptable to A X A F, and does as 
A Z A F does (reads file or files, selects buffers, etc.). 

firstlinep Emacs predicate 

returns truth if the current point is on the first line of 
the current buffer. 

fixp Lisp predicate 

returns truth if its argument is a fixnum (or bignum) . 
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format-to-col Emacs function 

puts whitespace in the current line at the current point, 
putting in at least one space. The argument is the column 
(zero-based) to format out to. 

fortran-mode-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering FORTRAN mode in a buffer. Used to customize 
key bindings, etc. 

forward-search Emacs function 

takes a string (or symbol) argument. Searches foward (as 
does. A S) in the current buffer, returning truth if the 
search succeeds (and moving point) or nil if not. 

fpathname Emacs per-buffer variable 

pathname (or nil if none) of file in current buffer. 

full-redisplay Emacs function 

clears the screen and redisplays all windows. 

funcall Lisp function 

..11» -. «,,„*»*. i *-.*•. / +. V>,» f ■? T>e+- ?i *-i-riiTn«*ri^ \ iir"i<M"« all flio reef flf 

V^&iXO d LUH^tiWll \ L11C kiidl. ti ^ ^ VMtlGll *-/ w*£/w«4 u A -*. w»w .www <w « 

its arguments. Needed only when the identity _ of the 
function to be called is not known, i.e., was obtained from 
the value of a variable. 

get Lisp special form 

first argument is a symbol, second a property. Obtains that 
property of that symbol, or nil if it hasn't one. 

get-char Emacs function 

returns (as a fixnum ASCII value) a single character read 
from the keyboard (or keyboard macro). Does not echo or 
prompt in any way. 

get-search-string Emacs function 

takes a prompt string. Gets a search string from the user 
(for use in writing search requests), and does defaulting 
and setting of defaults. 

go Lisp special form 

transfers to a PROG label. 

go-to-hpos Emacs function 

moves the current point to the character that would be at 
that (argument) , horizontal position (see cur-hpos for a 
definition of horizontal position). 

go-to-mark Emacs function 

argument is a mark that must be in the current buffer. 
Moves point to that mark. 
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go-to-or-create-buf fer Emacs function 

argument is a buffer symbol. Goes to that buffer, creating 
it if it does not exist. If it did exist, point will be 
where it last was in that buffer. 

ibase Lisp global variable 

base (normally 8) for converting numbers typed into Lisp. 

if Emacs special form 

special form for conditional execution. Evaluates its first 
form. if non-nil, evaluates all following forms up to 
"else" or end of the "if; otherwise, evaluates all forms 
after the "else" (if any). 

if-at Emacs special form 

first argument is a character symbol or string. Evaluates 
all the rest of its forms if the current character at the 
right of the point in the current buffer is this character. 

if-back-at Emacs special form 

same as if-at, but for the character to the left of the 
point. 

init-local-displays Emacs function 

sets up for local display output. 

insert-string Emacs function 

of one argument, a string (or symbol) of any length. 
Inserts those characters to the left of the current point 

ItoC Lisp function 

creates a single-character string from the ASCII value given 
as an argument* 

killsave-string Emacs function 

pushes its string (or symbol) argument onto the kill ring. 
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kill-pop Emacs function 

returns the first item on the kill ring and rotates the kill 
ring. 

kill-ring-top Emacs function 

returns the first item on the kill ring. 

lastlinep Emacs predicate 

returns truth if the current point is on the last line of 
the current buffer. If there is a newline in the file, this 
means the line (which may be empty) immediately after the 
last newlme. 

last-minibuffer-response Emacs per-buffer variable 

The last response given in the minibuffer. When ESC X opt 
remember-empty-response is set off, last-minibuffer-response 
is not set to blank when a blank response is given. 
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ldebug-mode-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering LDEBUG mode in a buffer. Used to customize 
key bindings, etc. 

lefthand-char Emacs function 

returns a single character symbol whose printname is the 
character to the left of point in the current buffer. 

let Lisp special form 

establishes variables and their bindings for a computation. 

line-is-blank Emacs predicate 

returns truth if the current line of the current buffer (the 
one on which point is) has no characters, or only whitespace 
characters. 

lisp-mode-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering LISP mode in a buffer. Used to customize key 

list Lisp function 

returns a list whose elements are list's arguments. 

list* Lisp function 

returns a list-like chain of conses, whose first n-1 
elements are list*'s first n-1 arguments, but the cdr of 
whose last cons is list*'s nth and last argument. 

local-display-current-line Emacs function 

displays the current line of the current buffer as local 
display (a local display must already have been 
established) . 

local-display-generator Emacs function 

takes a string (which must end in a newline) and displays it 
as local display. 

local-display-generator-nnl Emacs function 

like local-display-generator, but adds the newline for you. 

looking-at Emacs predicate 

returns truth if the string given as an argument (which must 
not contain a newline) appears immediately to the right of 
the current point in the current buffer, 
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mail -mode -hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering MAIL mode in a buffer. Used to customize kev 
bindings, etc. * 

maknam Lisp function 

makes a new symbol, not interned, whose name is formed from 
the supplied list of characters (symbols or fixnums, the 
latter interpreted as specifying ASCII values). 

mapc Lisp function 

?!!™ it f r ? t0 f ; first ar 9ument specifies a function. Second 
through last arguments are lists. The function is marched 
through the elements of the lists, in parallel. 

mark-at-current-point-p Emacs predicate 

takes a mark as argument. Returns truth if that mark 
specifies the place in the current buffer where the current 

mark-on-current-line-p Emacs predicate 

tafces a mark as argument. Returns truth if that mark 
S lf ;j s a point on the same line of the current buffer 
where the current point is. 

mark-reached Emacs predicate 

takes a mark as argument. Returns truth if current point 
na^ passed this mark in the current buffer. There are 
restrictions on this (see the writeup) . 

mark-same-line-p Emacs predicate 

takes two marks as arguments. Returns truth if thev 
represent points on the same line. Y 

memg Lisp predicate 

returns truth if its first argument is a member of the list 
tnat is its second argument. 

minibufjer-clear-all Emacs function , 

no- arguments, completely clears the minibuffer. j 

< * 

minibuff-er-response Emacs function . 

takes two arguments; the first is a prompt string, and the 

Itrtn* " ei £ er ^ >? ESC " prom P ts * he user with that 
nhll22+ in n ? e mir V buff ", requiring that termination 
character. Returns the string result of the user's typing! 

minibuffer-clear Emacs function 

clears the current line of the minibuffer. 
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minibuf f er-print Emacs function 

takes any number of arguments, expected to be strings or 
symbols, catenates and prints them in the minibuf fer. 

minibuf f er-print-noclear Emacs function 

like minibuf f er-print, but appends these strings to the last 
active line of the minibuf fer. 

nconc Lisp function 

like append,, but destructively rethreads its arguments to 
produce its. result. Be careful to utilize the result value 
of nconc, 

negate-minor-mode Emacs function 

asserts that a minor mode (specified by its symbol. argument ) 
is no longer in effect in the current buffer. The mode is 
removed from the mode line at the next redisplay. 

next-line Emacs function 

places the current point in the current buffer at the 
beginning of the next line in that buffer. 

nil Lisp global variable 

; v«~ <»ina. ie ifeaif nil uhirh is both the indicator of 

falsity and the emtpy list. 

NL Emacs global variable 

a symbol whose printname is an ASCII newline character. 

not Lisp predicate 

returns truth if its argument is the symbol "nil". 

nreverse Lisp function _ , . 

like reverse, but destructively rethreads the list it is 
given. Be careful to use the return value of nreverse. 

null Lisp predicate 

returns truth if its argument is the symbol "nil". 

null-stringp Emacs predicate 

returns truth if its argument is a null string or the symbol 
whose printname has no characters. 

nuwindows Emacs per-buffer variable 

the number of windows on the screen (not including 
minibuf fer or mode line). 

or Lisp special form 

evaluates all of its subforms sequentially until one is 

evaxuateu cu auyuuny uut uaa, w±. ±<~& xas>. «*»*— l»~... «w 

evaluated, whichever comes first. Returns the last form it 
evaluates. 
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pll-mode-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering PL/I mode in a buffer. Used to customize key 
bindings, etc. 

point-mark-to-string Emacs function 

returns as a string a copy of all text between the mark 
given as an argument and the current point in the current 
buffer. 

point>markp Emacs predicate 

takes a mark as an argument. Returns truth if the current 
point is further on in the buffer than the place represented 
by that mark. 

prev-line Emacs function 

moves the point to the beginning of the previous line of the 
current buffer. 

previous-buffer Emacs per-buffer variable 

the symbol of the previous buffer Emacs was in. 

print Emacs function 

prints out (to normal Multics output) the printed 
representation of its argument. 

process-char Emacs function 

called on a fixnum that is an ASCII character 
representation, interprets that character (includins readin" 
more, if necessary) as an Emacs request. 

process-dir Emacs global variable 

the pathname (a character string) of the process directory 
of the process using Emacs. 

prog Lisp special form 

sequentially evaluates forms within it, allowing use of 
local variables and labels. Returns nil, or the value 
supplied to "return". 

progl Lisp special form 

evaluates sequentially all of the forms within it, returning 
the value of the first. 

prog2 Lisp special form 

evaluates sequentially all of the forms within it, returning 
the value of the second. 

progn Lisp special form 

evaluates sequentially all of the forms within it, returning 
the value of the last. 
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protect Lisp special form 

evaluates and returns the value of its first subform. The 
remaining forms are then evaluated according to the success 
or failure of the first form's evaluation, as specified by 
special clauses. 

putprop Lisp function 

puts its second argument as the property specified by its 
third argument on its first argument, which must be a 
symbol. 

read-from-string- Lisp function 

performs a Lisp "read" operation on tue- contents Oj. w«e 
string supplied, creating (or finding) and returning the 
Lisp object whose printed representation was specified by 
the string. 

read-in-file Emacs function 

takes a pathname argument; reads it into the current buffer. 

read-only-flag Emacs per-buffer variable 

when set (when buf f er-modi.f ied-f lag has not yet been set) 
prevents a user from modifying the buffer. For 
pseudo-editable displays (like DIRED) . 

redisplay Emacs function 

updates the screen to reflect all changes in buffers on 
display. 

redisplay-current-window-relative Emacs function 

takes a line number on which to position the current line of 
the current buffer in the current window, where it is 
assumed to be on display. What A L with an argument does. 

regexp-search Emacs function 

like forward-search but does a "regular expression" search 
(as ESC / does) . 

register-local-variable Emacs function 
sets up a per-buffer variable. 

register-option Emacs function 

sets up an Emacs user option. First argument is a symbol 
(that is the option name and variable) and second argument 
is a default value. 

release-mark Emacs function 

takes a mark as an argument. Invalidates that mark, and 
frees Emacs from having to manage it any more. 
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report-error Emacs function 

of two arguments, error-code and error-information, aborts 
the current computation and prints an error. 

report-error-noabort Emacs function 

of two arguments, error-code and error-information, prints 
an error without aborting. 

return Lisp function 

returns a value from a do, prog, do-times, or do-forever. 

reverse Lisp function 

takes a list # as an argument, returns a list with the same 
elements but in opposite order. 

reverse-regexp-search Emacs function 

like reverse-search but does a "regular expression" search. 

reverse-search Emacs function 

searches backward for its (string or symbol) argument from 
the current point in the current buffer, as does A R (which 
uses it). Returns truth and moves point to before this 
string if the search succeeds. 

ring-tty-bell Emacs function 
beeps the tty bell. 

rmail-mode-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering RMAIL mode in a buffer. Used to customize kev 
bindings, etc. 

rotate-kill-ring Emacs function 
rotates the kill ring. 

rplacaLisp function 

first argument is a cons, the second is anything else. The 
second argument is made to be the car of the cons, which is 
returned as a value. 

rplacdLisp function 

first argument is a cons, the second is anything else. The 
second argument is made to be the cdr of the cons, which is 
returned as a value. 



2/83 B -25 



CJ52-01A 



Rprinc Emacs function 

to be used only by CTLS; "sends" a character string in raw 
mode to the terminal. This function does not work unless 
invoked by the CTL at redisplay time. 

Rtyo Emacs function 

to be used only by CTLS; "sends" a single character, 
specified by numeric ASCII value, in raw mode to the 
terminal. This function does not work unless invoked by the 
CTL at redisplay time. 
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samepnamep Lisp predicate 

returns truth if both arguments are symbols of the same 
printname, or strings of the same character-string value. 

save-excursion Emacs special form 

remembers where the point was in the current buffer when it 
was invoked, and restores it to there after evaluating the 
forms within. The value of save-excursion is the value of 
its- last evaluation. 

save-excursion-buf fer Emacs special, form 

remembers what buffer it was in when invoked, and restores 
Emacs to be in that buffer when exited after evaluating the 
forms within* 

| save-excursion-on-error Emacs special form 

| remembers where the point was in the current buffer when it 

| was invoked, and restores it to there if an error occurs 

J while evaluating the forms within. 

search-back-f irst-charset-line Emacs function 

takes a charscan table as an argument. Scans backward in 

a character in this charscan table. Returns truth and moves 
point if it succeeds. 

search-back-f irst-not-charset-line Emacs function 

takes a charscan table as an argument. Scans backward in 
the current line until the current point is to the right of 
a character not in this charscan table. Returns truth and 
moves point if it succeeds. 

search-charset-backward Emacs function 

takes a charscan table as an argument. Scans backward in 
the current buffer until the current point is to the right 
of a character in this charscan table. Returns truth and 
moves point if it succeeds. 

search-charset-forward Emacs function 

takes -a charscan table as an argument. Scans forward in the 
current line until the current point is to the left of a 
character in this charscan table. Returns truth and moves 
point if it succeeds. 

search-failure-annunciator Emacs function 

indicates that a search has failed, beeps, and aborts. To 
be used by search requests. 

search-for-f irst-charset-line Emacs function 

takes a charscan table as an argument. Scans forward in the 
current line until the current point is to the left of a 
character in this charscan table. Returns truth and moves 
point if it succeeds. 
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search-for-f irst-not-charset-line Emacs function 

takes a charscan table as an argument. Scans forward in the 
current line until the current point is to the left of a 
cnaracter not in this charscan table. Returns truth and 
moves point if it succeeds. 

search-not-charset-backward Emacs function 

takes a charscan table as an argument. Scans backward in 
the current buffer until the current point is to the right 
of a character in this charscan table. Returns truth and 
moves point if it succeeds. 

search-not-charset-forward Emacs function 

takes a charscan table as an argument. Scans forward in the 
current buffer until the current point is to the left of a 
character not in this charscan table. Returns truth and 
moves point if it succeeds. 

select-buffer-find-window Emacs function 

tries to put a buffer on the screen. See the section on 
window management. 

select-buffer-window Emacs function 

takes a buffer symbol and a line count as argument, and 
tries to get that buffer on the screen, putting it in the 
current window if it is not now on the screen. See the 
section on window management. 

select-window Emacs function 

takes a window number as argument. Moves the cursor to 
v selects) that window. 

selected-window Emacs per-buffer variable 

the window number of the window in which the cursor 
currently appears. 

set-buffer-self-destruct Emacs function 

takes a buffer symbol as argument. After this function is 
used, that buffer will be destroyed the first time it is 
exited. 

set-key Emacs function 

assigns key bindings in the current buffer. Takes two I 
arguments, the key name via a string or symbol, and the i 
function name via a symbol. The key name can be anything j 
like the names in the documentation, e.g., A X, A x, ESC ESC j 
A Xq, control-p, c-p, meta-f, ESC A f, etc. See Section 15 of I 
the Emacs Text Editor Users ' Guide for a full description of I 
acceptable key names. j 
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set-mark Emacs function 

creates a mark at the point where the current point is in 
the current buffer, and maintains it thereafter. Be sure to 
release-mark such marks, or use with-mark. 

set-permanent-key, set perm-key Emacs function 

sets a key to invoke a function in all buffers. Like 
set-key, takes two arguments, the keyname via a string or 
symbol, and the function name, via a symbol. See Section 15 
of. the Emacs Text Editor Users ' Guide for a full description 
of acceptable key names ~ 

setq Lisp special form 

assigns a value to a variable. 

skip-back-to-whitespace Emacs function 

moves current point backward in current buffer until a 
whitespace character (or the beginning of the buffer, 
whichever comes first) is to the left of it. 

skip-back-whitespace Emacs function 

moves current point, backward in current buffer until a 
non-whitespace character (or the beginning of the buffer, 
whichever comes first) is to the left of it. 

skip-back-whitespace-in-line Emacs function 

moves current point backward in current buffer until a 
non-whitespace character (or the beginning of the line, 
whichever comes first) is to the left of it. 

skip-over-whitespace Emacs function 

moves current point in current buffer forward over all 
whitespace characters until the first non-whitespace 
character. 

skip-over-whitespace-in-line Emacs function 

moves current point in current buffer forward over all 
whitespace until the end of the line. 

skip-to-whitespace Emacs function 

moves current point in current buffer over all 
non-whitespace characters until the next whitespace 
character. 

stop-doing Emacs special form 

causes do/do-forever to exit, returning nil. 

stringp Lisp predicate . 

returns truth if its argument is a string. 

symbolp Lisp predicate 

returns truth if its argument is a symbol. 
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t Lisp global variable 

its value is itself, which represents canonical truth. 

tab-equivalent Emacs per-buffer variable 

?urr"enr b u1rer? PaCeS * ^ iS ^^^ (norma11 * ten) in the 

text-mode-hook Emacs global variable 

tLt°r«n tl n ?r2 il? it: f binc ? in 3 is assumed to be a symbol 
,™« "J • Ca ii!2 aS . a ? unction as the last action of Emacs 
MnSings?^?. ""^ " * bu ""' ° Sed t0 atomize key J 

trace Lisp special form 

causes Lisp functions to be traced. 

unwind-protect Lisp special form 

evaluates and returns the value of its first subform. The 
eva a iat?In ^J™ are evaluated after the first form's 
-hnrSS .m,- 8 ? in * shed ' or when that first evaluation is 
aborted. This is how you set up a "cleanup handler". 

view-region-as-lines Emacs function 

displays the region in the current buffer as local display. 

whitespace-to-hpos Emacs function 

places whitespace, in optimal tabs and SDaces at th* 

current point in the current buffer, moving it until the 

reached? argument) horizontal position has been 

window-adjust-lower Emacs function 

adjusts the lower boundary line of a window. First argument 
is window number, second is how much to move it, signed. 

window-adjust-upper Emacs function 

adjusts the upper boundary line of a window. First argument 
is window number, second is how much to move it, signed. 

window-info Emacs function 

nfiK rnS - a 1 - St 0f inform ation about the window whose window 
number is given as an argument. 

wipe-point-rmark Emacs function 

bnf?L a K mark a ?u ar 9 umen t. Deletes all text in the current 
?Sf f ^ * et Y een the current point and this mark, saving it on 
the kill ring unless without-saving is being used. 

with-mark Emacs special form 

creates a mark in the current buffer at the place where the 
current point is when with-mark was invoked. The vlriable 
whose name appears first in the with-mark form is bound to 
this mark; with-mark frees this mark automatically. 
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without-modifying Emacs special form 

evaluates the forms within it, but the buffer is not marked 
as modified even though these forms may modify it. 

without-saving Emacs special form 

evaluates the forms contained within it, but the automatic 
saving of killed text on the kill ring is suppressed. 

write-out-file Emacs function 

takes a pathname argument. Writes the current buffer out to 
that filev 

yesp Emacs predicate 

takes a string argument. Asks the user that question in the 
minibuffer, and returns truth in response to a "yes" answer, 
rejecting all answers but "yes* or "no". 
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^arguments defcom keyword 

3-63, 3-64, 3-66, 3-68, 
3-69 

&cleanup defcom keyword 3-66, 
3-68, 3-69 

&completions defcom keyword 
3-66, 3-67 

^documentation defcom keyword 
3-66 

fcepilogue defcom keyword 3-65, 
3-68, 3-69 

&inverse defcom keyword 3-67, 
3-68 

tnegative-function 3-66 

tnegative-function defcom 
keyword 3-68 

Stnumeric-argument defcom 

keyword 3-61, 3-62, 3-66, 
3-68 

knumeric-function defcom 
keyword 3-62 

kprologue 3-66 



&prologue defcom keyword 3-65, 
3-68 

&undo defcom keyword 3-67 

(*rset t) mode 3-48 

*nopoint global variable 2-19 

+ function 2-2 

-function 2-1 

/(Lisp escape character) 2-11 



^/function 2—11 



< predicate 2-5 
= predicate 2-5 
> predicate 2-5 



add-error-code function 3-60 

addition 

♦function 2-1 

alphalessp predicate 2-6 

and special form 2-11 

append function 2-16 
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apply-catenate function 2-18, 
3-31 

ascii function 3-43 

assert-minor-mode function 
3-39 

at. predicate- 3-12 

at-beg inn ing-of -buffer 

at-end-of-buf fer predicate 
3-11 

at-white-char predicate 3-11 

attribute 

see symbol, property 

autophanic request 3-52 



B 

back-at predicate 3-12 

backquote 2-18, A-l 

base global variable 2-19 

binding 2-3, 2-16 

bolp predicate 3-11 

breakpoint 4-4 

buffer 

don t -not ice-modi f ied-buf fer 

3-29 
ldebug 4-1 
nontemporary 3-28 
symbol 3-27, 3-52 
temporary 3-27 

buf fer— creating 3-3, 3—26 

buffer-kill function 3-29 



buffer-minor-modes variable 
3-23, 3-39 

buf f er-modif ied-f lag variable 
3-22 

buf fer-on-di splay- in-window 
function 3-56 
predicate 3-56 

builtin function 

list ^2-14 
print 2-2 
rplaca 2-15 
rplacd 2-15 



car 2-13 

catenate function 3-31 

cdr 2-13 

character object 3-40 

character/number conversion 
3-43 

characters 

searching for 3-33 

charscan-table function 3-33 

char set -member predicate 3-34 

cleanup handler 
protect 3-10 

cleanup-handler 

unwind-protect 3-9 

command executing 
Multics 3-58 

command-quit function 3-18 

comment 2-1 
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comment-column variable 3-22 

comment-prefix variable 3-22 

comout-get-output 3-59 

compilation 3-48, 3-49 

compiling an extension 3-48 

cond special form 5-10 

cons 2-13 

construct 
see cons 

control argument 
-line_length 5-3 
-line_speed 5-3 
-page_length 5-3 
-query 5-2 
-terminal_type 5-2 

conversion 

character/number 3-43 
number/character 3-43 

CTL 5-1 

CTL functions 
see DCTL ■ 

Ctol function 3-43 

cur-hpos function 3-6 

curchar function 3-40 

current-buffer variable 3-29 

current-buffer-mode variable 
3-22, 3-38 

cursor position 
cur-hpos 3-6 
go-to-hpos 3-6 
predicates reflecting 3-11 



DCTL-clear-rest-of -screen 
function 5-6 

DCTL-delete-chars function 
5-8 

DCTL-delete-lines function 
5-7 

DCTL-di splay-char-st r ing 
function 5-5 

DCTL-epilogue function 5-7 

DCTL-init function 5-2, 5-4, 
5-6 

DCTL- insert-char-string 
function 5-7 

DCTL-insert-lines functions 
5-7 

DCTL-kill-line function 5-6 

DCTL-pos it ion-cursor function 
5-5 

DCTL-prologue function 5-7 

DCTL-scroll-down-region 
function 5-9 

DCTL-scroll-up-region function 
5-8 

debug-e function 3-48 

debugging 3-48, 4-1 

decimal-rep function 2-18, 
3-15 

declarations 3-49 

default specification 3-63 

defcom 3-61, 3-62, 3-63, 3-64, 
3-65, 3-66, 3-67, 3-68 
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defcom (cont) 
keywords 3-61 

&arguments 3-63, 3-64, 

3-66, 3-68, 3-69 
^cleanup 3-66, 3-68, 3-69 
&completions 3-66, 3-67 
kdocumentation 3-66 
&epilogue 3-65, 3-68, 

3-69 
^inverse 3-67, 3-68 
&negative-f unction 3-66, 

3-68 
&numeric-argument 3-61, 

3-62, 3-66, 3-68 
&numeric- function 3-62 
Sprologue 3-65, 3-68 
&undo 3-67 

defprop function 3-37 

defprop special form 3-37, 
3-50 

defvar special form 3-19 

delete-white-sides function 
3-13 

delete-window function 3-56 



display-buffer-as-print out 
function 3-25 

display-com-error function 
3-17 

display-com-error-noabort 
function 3-17 

display-error function 3-16 

display-error-noabort function 
3-17 

display-error-remark function 
3-18 

division 

//function 2-11 

do special form 5-11 

do-forever special form 2-9 

do-times special form 3-5 

documenting requests 3-50 
&doc 3-66 

dont-not ice-modi fied-buffer 
function 3-29 



deleting 
line 3-3 
region 3-3 

der-wahrer-mark variable 3-22 

destroy-buf fer-contents 
function 3-29 

dispatch-on-current-char 
special form 3-42 

dispatch-on-lef thand-char 
special form 3-42 

display 3-25 

display-as-pr intout special 
form 3-26 



element 2-13 

else keyword 2-7 

empty-buff er-p predicate 3-12, 
3-28 

end-local-displays function 
3-24 

entry value 4-3 

env-dir global variable 3-20 

eolp predicate 3-10 
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epilogue 3-65 

eq predicate 2-6, 3-40, 5-4 

error 3-8.1 

Emacs error system 3-60 

functions 3-60 
handling 4-1 
table 3-59 
trap entry 4-3 

error-table function 3-60 

error_table_ function 3-59 

ESC && (ldebug) 4-4 

ESC G (ldebug) 4-2, 4-3 

ESC global variable 3-16 

ESC L (ldebug) 4-4 

ESC P (ldebug) 4-4 

ESC R (ldebug) 4-4 

ESC T (ldebug) 4-3 

ESC A C(lisp) 3-49 

ESC A S (ldebug) 4-5 

escape character (Lisp) 2-11 

establish-local-var function 
3-21 

evaluation 2-2 
conditional 2-7 
of functions calls 2-3 
of numbers 2-3 
of strings 2-3 

execution 

see evaluation 

explode function 2-18 

explodec function 3-27 



extension 

definition of 1-1 

e cline 3-58 



file 

reading/writing 3-3 

f ill-mode-delimeters variable 
3-39 

f ind-buf fer-in-window function 
3-52 

find-f ile-subr function 3-3 

firstlinep predicate 3-11 

fixp predicate 2-6 

form 2-2, 2-3, 2-4, 2-16 
not 2-11 
special 2-6 

and 2-11 

cond 5-10 

defprop 3-37, 3-50 

defun 2-7 

defvar 3-19 

dispatch-on-current-char 
3-42 

dispatch-on-lefthand-char 
3-42 

display-as-printout 3-26 

do 5-11 

do-forever 2-9 

do-times 3-5 

get 3-27 

go 2-10 

if 2-7 

i-f-at 3-41 

if-back-at 3-41 

let 2-9 

or 2-11 

prog 2-10 

progl 2-12 

progn 2-11 

protect 3-10 

putprop 3-27 
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form (cont) 
special 

save-excursion 3-7 
save-excurs ion-buffer 

3-29 
save-excursion-on-error 

3-7 
setq 2-8 
• unwind-protect 3-9 
with-mark 3-6. 
without-modifying 3-8 
without- saving 3-5 
stop-doing 2-9 

format-to-col function 3-14 

forward-search function 3-3 

forward-search- in-line 
function 3-15 

fpathname variable 3-22 

f ull-redi splav function 3-4, 
3-32,^3-33 

funcall function 3-38, 3-39 

function 2-1, 2-4 
add-error-code 3-60 
append 2-16 

apply-catenate 2-18, 3-31 
ascii 3-43 

assert-minor-mode 3-39 
buffer-kill 3-29 
buf f er-on-di splay- in-window 

3-56 
car 2-13 
catenate 3-31 
cdr 2-13 

charscan-table 3-33 
command-quit 3-18 
comout-get-output 3-59 
cons 2-13 
Ctol 3-43 
cur-hpos 3-6 
curchar 3-40 
DCTL-clear-rest-of -screen 

5-6- 
DCTL-delete-chars 5-8 
DCTL-delete-lines 5-7 



function (cont) 

DCTL-di splay-char-string 

5-5 
DCTL-epilogue 5-7 
DCTL-init 5-4 

DCTL-insert-char-string 5-7 
DCTL-insert-lines 5-7 
DCTL- kill-line 5-6 
DCTL-posit ion-cursor 5-5 
DCTL-prologue 5-7 
DCTL.-scroll-down-region 5-9 
DCTL.-scroll-up- region 5-8 
decimal-rep 2-18 ~ 3-15 
definition 2-1 
delete-white-sides 3-13 
delete-window 3-56 
destroy-buf fer-con tents 

3-29 
display-buff er-as-printout 

3-25 
display-com-error 3-17 
display-com-error-noabort 

3-17 
di s^la 1 '— er r or 3—^ 5 
display-error-noabort 3-17 
display-error-remark 3-18 
don t-not ice-modi f ied-buf fer 

3-29 
Bmacs requests 3-1 

exceptions 3-2 
end-local-displays 3-24 
error-table 3-60 
error_table_ 3-59 
establish-local-var 3-21 
explode 2-18 
explodec 3-27 
e_ r cline_ 3-58 
fTnd-buf f er-in-window 3-52 
f ind-f ile-subr 3-3 
for CTLs 5-2 
format-to-col 3-14 
forward-search 3-3 
forward-search-in-line 3-15 
full-redisplay 3-4, 3-32, 

3-33 
funcall 3-38, 3-39 
get-char 3-43 
get-search-string 3-57 
go-to-hpos 3-6 
go—to-mar k 3-6 
go-to-or-create-buf fer 3-3, 

3-27 
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function (cont) 

init-local-displays 3-24 

insert-string 3-4 

ItoC 3-43 

kill-pop 3-8.1, B-5.1, 

B-19.1 
kill-ring-top 3-8.1, B-5.1, 

B-19.1 
killsave-string 3-8 
lefthand-char 3-41 
list 2-14 
list* 2-15 

local-display-current-line 
3-25 

local-display-generator 

3-24 
maknam 2-18, 3-27 
mapc 3-39 

minibuf fer-clear 3-17 
minibuffer-clear-all 3-16 
minibuf fer-print 3-15 
minibuf fer-print-noclear 

3-17 

minibuf fer-response 3-16 
nconc 2-16 

negate-minor-mode 3-39 
next-line 3-3 
nreverse 2-16 
point-mark-to-string 3-3, 

3-14 
prev-line 3-3 
process-char 3-44 
read-f rom-string 2-19 
read-in-file 3-3 
redisplay 3-31 
redi splay-current-window 

-relative 3-4, 3-33 
regexp-search 3-3 
regexp-search-in-line 3-15 
register-local-variable 

3-20 
register-option 3-35 
release-mark 3-5 
report-error 3-60 
report =error-noabort 

function 3-60 
reverse 2-16 
reverse-regexp-search 

B-8, B-25 
reverse-search 3-3 
reverse-search-in-line 3-15 
ring-tty-bell 3-18 



function (cont) 

rotate-kill-ring 3-8.1, 

B-5.1, B-25 
Rprinc 5-4 
Rtyo 5-4 
search-back-first 

-charset-line 3-34 
search-back-first-not 
-charset-line 3-34 
search-charset-backward 

3-34 
search-charset-forward 3-34 
search-failure-annunciator 
3-57 

search-for-f irst 

-charset-line 3-34 

search-for-f irst-not 
-charset-line 3-34 

search-not-char set-backward 
3-34 

search-not-char set-forward 
3-34 

select-buffer- find-window 

3-54 
select-buffer-window 3-53 
select-window 3-56 

set-buffer-self-destruct 

3-28 
set-key 3-38 
set-mark 3-5 
SkiD-back-to-whitesnar* 

* 3-13 "" *" 
skip-back-whitespace 3-13 

skip-back-whitespace-in-line 
3-13 

skip-over-whitespace 3-13 

skip-over-whitespace-in-line 
3-13 

skip-to-whitespace 3-13 
stringlength 5-5 
view-region-as-lines 3-25 
whitespace-to-hpos 3-14 
window-adjust-lower 3-56 
window-adjust-upper 3-56 
window-info 3-56 
wipe-point-mark 3-3, 3-5 
write-out-f ile 3-3 



function call 
syntax 2-3 



2-4 
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get special form 3-27 

get-char function 3-43 

get-search-string function 
3-57 

given-tty-type variable 5-4 

global variable 
nil 2-8 

see variable, global 
t 2-8 

go special form 2-10 

go-to-hpos function 3-6 
as predicate 3-6 

go-to-mark function 3-6 

go-to-or-creat-buf fer function 
3-3 

go-to-or-create-buf fer 3-26 

go-to-or-create-buf f er 

function 3-26, 3-27 



H 



heterophanic request 3-52 

hook 

mode 3-23 



ibase global variable 2-19 

if special form 2-7 
syntax 2-7 

if-at special form 3-41 



if-back-at special form 3-41 

indicator 3-26 

init-local-displays function 
3-24 

insert-string function 3-4 

interned symbol 3-26 

ItoC function 3-43 



K 



keyword 
else 2-7 

kill-pop function 3-8.1, 
B-5.1, B-19.1 

B-5.1, B-19.1 
killsave-string function 3-8 



label 2-10 

last-mini buffer- response 
variable 3-16 

lastlinep predicate 3-11 

Idebug mode 

Idebug-di splay-where 
-editor-was 
ESC A S 4-5 

Idebug- list-breaks 
ESC L 4-4 

Idebug- re set- break 
ESC R 4-4 
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Idebug- re turn- to-emacs 
-top-level 
ESC G 4-2 

Idebug- trace-stack 
ESC T 4-3 

lefthand-char function 3-41 

let special form 2-9 
syntax 2-10 

line-is-blank predicate 3-12 

Lisp debug mode 
see Idebug 

Lisp macro A-l 
see macro 

Lisp macros 3-49 

list 2-13 

list function 2-14, 2-15 

loading an extension 3-1, 
3-45 

local display 3-24 

local variable 

see variable, local 

local-display-current-line 
function 3-25 

local -display-generator 
function 3-24 

looking-at predicate 3-2, 
3-11 

looping 

see do-forever 2-S 



M 



macro 2-17 



macro character 
backguote A-l 
comma A-l 

major mode 
see mode 

maknam function 2-18 

maknem function 3-27 

mapc function 3-39 

mark 3-5 

go-to-mark 3-6 
predicates 3-11 
release-mark 3-5 
save-excursion 3-7 
set-mark 3-5 
temporary 3-5 
wipe-point-mark 3-3 
with-mark 3-6 

mark-at-current-point-p 
predicate 3-11 

mark-on-current-line-p 
predicate 3-12 

mark-reached predicate 3-11 

mark-same-line-p predicate 
3-12 

memq predicate 3-39 

minibuffer 3-15 

functions 3-16, 3-17 
yesp 3-12 

minibuf fer-clear function 
3-17 

minibuffer-clear-all function 
3-16 

minibuf fer-print function 
3-15 

minibuf fer-pr in t-noclear 
function 3-17 
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minibuf f er-response function 
3-16 

minor mode 
see mode 

mode 

hook 3-23 
Idebug 4-1 
major 3-37 
minor 3-3.7, 3-39 

mode-hook 3-39 

multiple windows 
see windows 

multiplication 
♦function 2-1 



N 



names 

choosing 3-36 

nconc function 2-16 

negate-minor-mode function 
3-39 

negative function 3-66 

negative-function defcom 
' keyword 3-66 

next-line function 3-3 

nil global variable 2-8 

nil symbol 3-4 

NL global variable 3-16 

not form 2-11 

nreverse function 2-16 



mil 1 ^v-e/3-i^-s^^ *3 — £ 



null-stringp predicate 3-12 



numarg global variable 3-4 

number/character conversion 
3-43 

numeric arguments 3-4 
do-times 3-5 

nuwindows variable 3-55 



obarray 2-12, 3-26 
object 2-6, 2-18 
object, program 3-48 
operand 2-10 
option 3-35 
or special form 2-11 
ospeed variable 5-3 



parentheses 2-3 

per-buffer variable 
see variable, local 

point-mark-to-string function 
3-3, 3-14 

point>markp predicate 3-11 

pop-up window mode 3-53 

predicate 2-5 
< 2-5 
= 2-5 
> 2-5 
alphalessp 2-6 

at-beginning-of-buf f er 3-11 
at-end-of-buf f er 3-11 
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predicate (cont) 

at-white-char 3-11 

back-at 3-12 

bolp 3-11 

buf fer-on-di splay- in-window 

3-56 
char set -member 3-34 
empty-buff er-p 3-12, 3-28 
eolp 3-10 
eq 2-6, 3-40, 5-4 
firstlinep 3-11 
f.ixp 2-6 
go-to-hpos 3-6 
lastlinep 3-11 
line-is-blank 3-12 
looking-at 3-2, 3-11 

mark-at-current-point-p 
3-11 

mark-on-current-line-p 3-12 
mark-reached 3-11 
mark-same-line-p 3-12 
memq 3-39 
null 2-6 

null-stringp 3-12 
point>markp 3-11 
samepnamep 2-6 
stringp 2-6 
symbolp 2-6 
yesp 3-12 

prev-line function 3-3 

previous-buffer variable 3-29 

print function 2-2 

printname 2-12 

problem 

monitoring 3-21 

proces-dir global variable 
3-20 

process=char function 3-44 

prog special form 2-10 

progl special form 2-12 

progn special form 2-11 



prologue 3-65 

prompting 

&prompt 3-64 

minibuf fer-response 3-16 

property 2-16, 3-26 
documentation 3-50 

protect special form 3-10 

putprop special form 3-27 



read-f rom-string function 
2-19 

read-in-file function 3-3 

read-only-flag variable 3-22 

redisplay 3-31, 3-33 

redisplay function 3-31 

redi splay-current-window 

-relative function 3-4, 

regexp-search function 3-3 

regexp-search-in-line function 
3-15 

region 

copying 3-3 
deleting 3-3 

region scrolling 5-8 

region-scroll-availablep 
variable 5-8 

register-local-variable 
function 3-20 

register-option function 3-35 
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registering a variable 
functions 3-20 

release-mark function 3-5 

report-error function 3-60 

return function 2-9 

returned value 2-1 

reverse-regexp-search function 

■e»_q »_->e 

reverse function 2.-16 

reverse-search function 3-3 

reverse-search- in-line 
function 3-15 

ring-tty-bell function 3-18 

rotate-kill-ring function 
3-8.1, B-5.1, B-25 

rplaca function 2-15 

rplacd function 2-15 

Rprinc function 5-4 

Rtyo function 5-4 



samepnamep predicate 2-6 

save-excursion special form 
3-7 

save-excursion-buf fer special 
form 3-29 

save-excursion-on-error 
special form 3-7 

scanning character 3-33 

screen 3-33 



scrolling 
region 5-8 

search-back- first-char set-line 
function 3-34 

search-back- f irst-not 

-charset-line function 3-34 

search-char set-backward 
function 3-34 

search-char set- forward 
function 3-34 

search-failure-annunciator 
function 3-57 

search- for-f irst-char set-line 
function 3-34 

search- for-f irst-not 

-charset-line function 3-34 

search-not-char set-backward 
function 3-34 

search-not-char set- forward 
function 3-34 

searching 3-57 

forward-search-in-line 3-15 
foward-search 3-3 
get-search-string 3-57 
regexp-search 3-3 
regexp-search-in-line 3-15 
reverse-regexp-search B-8, 

B-25 
reverse-search 3-3 
reverse-search-in-line 3-15 
search-failure-annunciator 

3-57 

select-buffer- find-window 
function 3-54 

select-buffer-window function 
3-53 

select-window function 3-56 

selected-window variable 3-55 
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set-buffer-self-destruct 
function 3-28 

set-key (ESC 2) 3-1 

set-key function 3-21, 3-38 

set-mark function 3-5 

set-permanent-key (ESC 2) 3-1 

setq special form 2-8 

skip-back-to-whitespace 
function 3-13 

skip-back-whitespace function 
3-13 

skip-back-whitespace- in-line 
function 3-13 

skip-over-whitespace function 
3-13 

skip-over-whitespace-in-line 
function 3-13 

skip-to-whitespace function 
3-13 

special form 
defcom 3-61 
see form 

special varibale 
see variable 
global 

stop-doing form 2-9 

string form 3-40 

stringlength function 5-5 

stringp predicate 2-6 

subtraction 

-function 2-1 

symbol 2-6, 2-16 
definition of 2-12 



symbol (cont) 
interned 3-26 
property 3-26 
registry 3-26 

symbolp predicate 2-6 



t global variable 2-8 

tab-equivalent variable 3-22 

temp-mark variable 3-5 

temporary 
mark 3-5 
variable 2-10 

terminal support 5-1 

terminal type file 5-1 

the-mark global variable 3-5 

trace 4-5 

tracing function 4-4 

tty-type variable 5-4 



unwind-protect special form 
3-9 



variable 2-3 

binding 2-3 

current-buffer 3-29 

defvar 3-19 

given-tty-type 5-4 

global 2-4, 3-18, 3-35 
*nopoint 2-19 
aim-mode-hook 3-23 
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variable (cont) 
global 

base 2-19 

buffer-creation-hook 3-24 
buffer-destruction-hook 

3-24 
buffer-entrance-hooks 

3-24 
buffer-exit-hook 3-24 
character object 3-41 
close-line-hook 3-24 
current-buffer 3-27 
env-dir 3-20 
ESC 3-16 

f ill-mode-delimeters 3-39 
fortran-mode-hook 3-23 
ibase 2-19 

ldebug-mode-hook 3-23 
lisp-mode-hook 3-23 
mail-mode-hook 3-23 
nil 2-8 
NL- 3-16 
numarg 3-4 

I r>l 1 — fflftda- Vi/"ir\lr "5 — 01 

process-dir 3-20 

rmail-mode-hook 3-23 

see mode hook 

t 2-8 

t he-mark 3-5 

X, Y 5-4 
last-minibuf fer-response 

3-16 
ldebug-level 4-2 
local 3-20 

automatically registered 
3-22 

buffer-minor-modes 3-39 

current-buffer-mode 3-38 
nuwindows 3-55 
option 

ldebug-base 4-2 

ldebug-ibase 4-2 

ldebug-prinlength 4-2 

ldebug-prinlevel 4-2 
ospeed 5-3 
parameter 2-4 
previous-buffer 3-29 
region-scroll-availablep 
5-8 

tegiateiiiiy j iu 

selected-window 3-55 



variable (cont) 
special 

se global 
temp-mark 3-5 
temporary 2-4, 2-9 
trace-break-fun 4-7 
trace-printer 4-7 
tty-type 5-4 

view-region-as-lines function 
3-25 



W 



whitespace 

functions 3-13 
management 3-13 

whitespace-to-hpos function 
3-14 

window 3— 33 
number 3-55 

pop-up window mode 3-53 
selected 3-55 

window-adjust-lower function 
3-56 

window-adjust-upper function 
3-56 

window-info function 3-56 

windows 

multiple 3-52 

wipe-point-mark function 3-3, 
3-5 

with-mark special form 3-6 

without-modifying special form 
3-8 

without-saving special form 
3-8 

write-out-f ile function 3-3 
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X 



X global variable 5-4 



Y global variable 5-4 
yesp predicate 3-12 
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